@seriousgaming/sdk-tools 1.0.0-alpha.4 → 1.1.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.
- package/README.md +4 -4
- package/dist/brands/awkward/brand.json +16 -0
- package/dist/brands/awkward/logo-on-light.svg +4 -0
- package/dist/brands/serious-gaming/brand.json +42 -0
- package/dist/brands/serious-gaming/fonts/OFL-sora.txt +93 -0
- package/dist/brands/serious-gaming/fonts/OFL-work-sans.txt +93 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-400-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-600-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/sora-latin-700-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/fonts/work-sans-latin-wght-normal.woff2 +0 -0
- package/dist/brands/serious-gaming/icon.svg +24 -0
- package/dist/brands/serious-gaming/loader-on-dark.svg +25 -0
- package/dist/brands/serious-gaming/loader-on-light.svg +25 -0
- package/dist/brands/serious-gaming/logo-on-dark.svg +38 -0
- package/dist/brands/serious-gaming/logo-on-light.svg +42 -0
- package/dist/cli.js +20003 -5523
- package/dist/client.js +15534 -1134
- package/dist/core/save-scenario.d.ts +25 -0
- package/dist/core/session-endpoints.d.ts +12 -13
- package/dist/core/session-host.d.ts +9 -1
- package/dist/core/session-writes.d.ts +2 -2
- package/dist/core/session.d.ts +9 -1
- package/dist/dev/brand-summary.d.ts +16 -0
- package/dist/dev/brands.d.ts +213 -0
- package/dist/dev/console/assets/icon-CRaj5uhr.svg +24 -0
- package/dist/dev/console/assets/index-q6-lvlN3.css +1 -0
- package/dist/dev/console/assets/index-qxHcu9fJ.js +204 -0
- package/dist/dev/console/assets/sora-latin-400-normal-CRt88UEn.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-600-normal-Cdg4DaK0.woff2 +0 -0
- package/dist/dev/console/assets/sora-latin-700-normal-9waGdLWo.woff2 +0 -0
- package/dist/dev/console/assets/work-sans-latin-wght-normal-Bl-S9Xys.woff2 +0 -0
- package/dist/dev/console/index.html +3 -1
- package/dist/dev/routes.d.ts +9 -0
- package/dist/dev/shell.d.ts +14 -0
- package/dist/dev/view/batch.d.ts +0 -2
- package/dist/docs/ai-agents.md +75 -0
- package/dist/docs/api/deck.md +38 -0
- package/dist/docs/api/index.md +5 -5
- package/dist/docs/api/sdk-commands.md +1 -1
- package/dist/docs/api/sdk-e2e.md +1 -0
- package/dist/docs/api/sdk-projection.md +1 -0
- package/dist/docs/api/sdk-testing.md +52 -1
- package/dist/docs/api/sdk-tools-client.md +1 -0
- package/dist/docs/api/sdk-ui-testing.md +30 -4
- package/dist/docs/api/sdk-ui.md +166 -0
- package/dist/docs/api/sdk.md +70 -4
- package/dist/docs/changelog.md +64 -6
- package/dist/docs/cli-and-dev-server.md +2 -0
- package/dist/docs/cli-error-codes.md +65 -59
- package/dist/docs/cli-reference.md +84 -45
- package/dist/docs/concepts/index.md +74 -6
- package/dist/docs/concepts/terminology.md +17 -11
- package/dist/docs/getting-started.md +30 -11
- package/dist/docs/guides/ai-facilitation.md +5 -1
- package/dist/docs/guides/capabilities.md +3 -1
- package/dist/docs/guides/designing-a-game.md +85 -0
- package/dist/docs/guides/endpoints.md +57 -13
- package/dist/docs/guides/engine-testing.md +4 -13
- package/dist/docs/guides/engine.md +14 -2
- package/dist/docs/guides/file-handling.md +14 -10
- package/dist/docs/guides/games.md +2 -8
- package/dist/docs/guides/guide.md +64 -3
- package/dist/docs/guides/index.md +3 -4
- package/dist/docs/guides/internationalization.md +8 -14
- package/dist/docs/guides/llm-integration.md +19 -31
- package/dist/docs/guides/multi-team-games.md +9 -14
- package/dist/docs/guides/patterns.md +0 -6
- package/dist/docs/guides/presentation.md +6 -10
- package/dist/docs/guides/production-constraints.md +2 -9
- package/dist/docs/guides/scenario-editor.md +11 -11
- package/dist/docs/guides/scenarios.md +26 -14
- package/dist/docs/guides/session.md +29 -35
- package/dist/docs/guides/settings.md +28 -2
- package/dist/docs/guides/setup.md +2 -7
- package/dist/docs/guides/speech-generation.md +8 -17
- package/dist/docs/guides/starter-game.md +2 -1
- package/dist/docs/guides/testing.md +45 -43
- package/dist/docs/guides/theming-and-branding.md +194 -0
- package/dist/docs/guides/tick-controller.md +8 -4
- package/dist/docs/guides/type-safety.md +8 -6
- package/dist/docs/guides/ui.md +41 -62
- package/dist/docs/guides/upgrading.md +28 -3
- package/dist/docs/guides/validators.md +64 -3
- package/dist/docs/guides/waiting-room.md +3 -10
- package/dist/docs/index.md +40 -10
- package/dist/docs/recipes/adapt-ui-for-observers.md +1 -1
- package/dist/docs/recipes/call-endpoint-from-ui.md +2 -0
- package/dist/docs/recipes/create-capability.md +1 -1
- package/dist/docs/recipes/create-endpoint.md +7 -2
- package/dist/docs/recipes/create-engine.md +1 -1
- package/dist/docs/recipes/create-guide.md +2 -2
- package/dist/docs/recipes/create-hook.md +1 -1
- package/dist/docs/recipes/create-session-ui.md +1 -1
- package/dist/docs/recipes/create-settings.md +1 -1
- package/dist/docs/recipes/create-tick-controller.md +1 -1
- package/dist/docs/recipes/create-user-interface.md +1 -1
- package/dist/docs/recipes/create-validator.md +1 -1
- package/dist/docs/recipes/declare-api-uses.md +2 -2
- package/dist/docs/recipes/design-state-for-concurrent-writes.md +2 -2
- package/dist/docs/recipes/distribute-package.md +3 -3
- package/dist/docs/recipes/e2e-testing.md +11 -9
- package/dist/docs/recipes/index.md +6 -2
- package/dist/docs/recipes/make-a-guide-follow-the-scenario.md +89 -0
- package/dist/docs/recipes/make-an-endpoint-external.md +1 -1
- package/dist/docs/recipes/publish-a-package.md +1 -1
- package/dist/docs/recipes/remember-a-viewers-choice.md +1 -1
- package/dist/docs/recipes/review-a-past-day.md +4 -2
- package/dist/docs/recipes/share-assets-across-scenarios.md +3 -3
- package/dist/docs/recipes/share-logic-between-engine-and-ui.md +1 -1
- package/dist/docs/recipes/test-a-multi-role-game.md +1 -1
- package/dist/docs/recipes/test-user-interface.md +13 -2
- package/dist/docs/recipes/validate-scenarios.md +91 -0
- package/dist/docs/troubleshooting.md +44 -2
- package/dist/execution/blob-inputs.d.ts +7 -2
- package/dist/execution/config-resolver.d.ts +10 -0
- package/dist/execution/endpoint-runner.d.ts +8 -1
- package/dist/execution/executor-callbacks.d.ts +7 -0
- package/dist/execution/executor.d.ts +11 -0
- package/dist/execution/logic-calls.d.ts +8 -1
- package/dist/execution/scenario-gates.d.ts +34 -0
- package/dist/guide/effective-guide.d.ts +20 -0
- package/dist/guide/locale.d.ts +12 -0
- package/dist/guide/settings.d.ts +67 -0
- package/dist/host/host-channel.d.ts +11 -2
- package/dist/host/index.d.ts +7 -1
- package/dist/host/protocol.d.ts +49 -5
- package/dist/host/theme.d.ts +28 -2
- package/dist/host.js +11490 -15
- package/dist/runtime/index.d.ts +1 -1
- package/dist/runtime/manifest-version.d.ts +17 -0
- package/dist/runtime.js +12 -1
- package/dist/schema.json +32 -4
- package/dist/storage/blob-store.d.ts +3 -2
- package/dist/templates/endpoint/logic.test.ts.liquid +19 -1
- package/dist/templates/endpoint/logic.ts.liquid +18 -0
- package/dist/templates/hook/logic.test.ts.liquid +2 -2
- package/dist/templates/package/CLAUDE.md.template +5 -2
- package/dist/templates/package/README.md.liquid +2 -0
- package/dist/templates/package/claude/rules/workflow-create-endpoint.md +5 -4
- package/dist/templates/package/claude/rules/workflow-create-guide.md +1 -0
- package/dist/templates/presentation/src/App.tsx.liquid +5 -11
- package/dist/templates/session/src/App.test.tsx.liquid +2 -4
- package/dist/templates/session/src/theme.ts.liquid +26 -33
- package/dist/templates/settings-editor/src/theme.ts.liquid +13 -18
- package/dist/templates/starter-game/hooks/assignproducts/logic/logic.test.ts +2 -8
- package/dist/templates/starter-game/session/src/App.test.tsx +6 -10
- package/dist/templates/starter-game/session/src/theme.ts +26 -33
- package/dist/templates/starter-game/ui/src/App.tsx +2 -0
- package/dist/templates/starter-game/ui/src/HostLogo.test.tsx +25 -0
- package/dist/templates/starter-game/ui/src/HostLogo.tsx +38 -0
- package/dist/templates/starter-game/ui/src/theme.ts +26 -33
- package/dist/templates/starter-game/validators/capacity/types.ts +2 -0
- package/dist/templates/starter-game/waiting_room/src/theme.ts +26 -33
- package/dist/templates/ui/src/App.test.tsx.liquid +7 -19
- package/dist/templates/ui/src/theme.ts.liquid +26 -33
- package/dist/templates/validator/logic.ts.liquid +4 -0
- package/dist/templates/waiting-room/src/App.test.tsx.liquid +17 -31
- package/dist/templates/waiting-room/src/theme.ts.liquid +26 -33
- package/dist/utils/error-codes.d.ts +15 -3
- package/dist/validation/ajv.d.ts +9 -5
- package/dist/validation/facilitator-guide-validator.d.ts +6 -0
- package/dist/validation/file-settings.d.ts +49 -0
- package/dist/validation/guide-settings-validator.d.ts +26 -0
- package/package.json +6 -5
- package/dist/dev/console/assets/index-DgFglsnA.js +0 -204
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Validate a game's scenarios
|
|
2
|
+
|
|
3
|
+
Refuse a scenario whose settings break your game's rules, at build and when one is saved, never when a session starts.
|
|
4
|
+
|
|
5
|
+
**Keywords:** validate scenario, scenario rules, settings conflict, required scenario value, empty default, Scenario gate, scenario-validation, custom scenario check
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
8
|
+
|
|
9
|
+
- A settings resource holding the values the rule is about (here `ui`, with `MinPrice` and `MaxPrice`); see [Create a settings resource](create-settings.md)
|
|
10
|
+
- `seriousgaming.sdk.json` in your working directory
|
|
11
|
+
|
|
12
|
+
## Steps
|
|
13
|
+
|
|
14
|
+
1. Put the rules in a file both the gate and your scenario editor can import, `shared/scenario-rules.ts`, as plain functions with no browser or Node APIs:
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
export interface ScenarioRuleProblem {
|
|
18
|
+
path: string;
|
|
19
|
+
message: string;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function scenarioProblems(ui: {
|
|
23
|
+
MinPrice: number;
|
|
24
|
+
MaxPrice: number;
|
|
25
|
+
}): ScenarioRuleProblem[] {
|
|
26
|
+
const problems: ScenarioRuleProblem[] = [];
|
|
27
|
+
if (ui.MinPrice > ui.MaxPrice) {
|
|
28
|
+
problems.push({
|
|
29
|
+
path: 'ui.MinPrice',
|
|
30
|
+
message: `The lowest price (£${ui.MinPrice}) must be at or below the highest price (£${ui.MaxPrice})`,
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
return problems;
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Name the setting in `path` and say what is allowed in `message`: an agent editing a scenario has nothing else to go on. For a value every scenario must supply, default it to an empty one and refuse that here, as in `if (edition.ClientName === '')`.
|
|
38
|
+
|
|
39
|
+
2. Create a validator that reads the settings and no capabilities:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pnpm run sdk new validator '{
|
|
43
|
+
"definition": {
|
|
44
|
+
"identifier": "scenariocheck",
|
|
45
|
+
"settings": ["ui"]
|
|
46
|
+
},
|
|
47
|
+
"logic": { "directory": "logic", "entrypoint": "logic.ts" },
|
|
48
|
+
"rootDirectory": "."
|
|
49
|
+
}'
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
3. Replace the scaffolded `UpdateData` in `validators/scenariocheck/logic/logic.ts` with a `Scenario` gate:
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
import { scenarioProblems } from '../../../shared/scenario-rules';
|
|
56
|
+
import type { ScenarioFunction } from '../types';
|
|
57
|
+
|
|
58
|
+
export const Scenario: ScenarioFunction = async ({ settings }) => scenarioProblems(settings.ui);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Update the scaffolded `logic.test.ts` to call `Scenario({ settings, locale: 'en' })` and check the problems it returns.
|
|
62
|
+
|
|
63
|
+
4. List the feature in `seriousgaming.sdk.json`:
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"requires": ["scenario-validation"]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
5. If facilitators have already saved scenarios for a released version, bump `scenarioFormat` in the same file, so the runtime stops using scenarios saved before the rule
|
|
72
|
+
|
|
73
|
+
6. Optionally, show the same problems in your scenario editor by calling `scenarioProblems(settings.ui)` and marking each field whose setting a problem names
|
|
74
|
+
|
|
75
|
+
## Verify
|
|
76
|
+
|
|
77
|
+
- `pnpm run sdk build --validate-only` passes
|
|
78
|
+
- Set `"MinPrice": 600, "MaxPrice": 400` under `settings.ui` in one of your scenarios and run it again: it fails with `SCENARIO_REFUSED`, pointing at `MinPrice` in that scenario's file
|
|
79
|
+
|
|
80
|
+
## Troubleshooting
|
|
81
|
+
|
|
82
|
+
- _`FEATURE_UNDECLARED` at `/requires`_: add `"scenario-validation"` to `requires`
|
|
83
|
+
- _`SCENARIO_REFUSED` for 'The defaults'_: no scenario is the default, so a session can run on the defaults alone, and they break a rule. Mark a scenario `"default": true`, or change the defaults
|
|
84
|
+
- _A placeholder that is also a real choice_: the gate sees values, not where they came from, so it cannot tell a scenario that chose `0` from one that forgot. Use an obviously empty default (`""`, `[]` or `{}`)
|
|
85
|
+
- _'Validator scenariocheck threw'_: the gate threw, which counts as a problem so that a broken rule never lets a scenario through. Check the settings it reads are listed in `settings`
|
|
86
|
+
|
|
87
|
+
## Related
|
|
88
|
+
|
|
89
|
+
- [Validators guide: gating scenarios](../guides/validators.md#gating-scenarios)
|
|
90
|
+
- [Create a validator](create-validator.md)
|
|
91
|
+
- [Building a scenario editor](../guides/scenario-editor.md)
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Find the symptom you are seeing, then read its cause and fix. Entries are grouped by where the problem shows up.
|
|
4
4
|
|
|
5
|
+
- [Scaffolding and install](#scaffolding-and-install)
|
|
5
6
|
- [Dev server and sessions](#dev-server-and-sessions)
|
|
6
7
|
- [Engine logic and endpoints](#engine-logic-and-endpoints)
|
|
7
8
|
- [Build and validation](#build-and-validation)
|
|
@@ -9,6 +10,39 @@ Find the symptom you are seeing, then read its cause and fix. Entries are groupe
|
|
|
9
10
|
- [Tests](#tests)
|
|
10
11
|
- [Other error messages](#other-error-messages)
|
|
11
12
|
|
|
13
|
+
## Scaffolding and install
|
|
14
|
+
|
|
15
|
+
### `pnpm dlx @seriousgaming/sdk-tools new package` fails before it asks anything
|
|
16
|
+
|
|
17
|
+
**Symptom:** the command exits at once, or says `pnpm: command not found`.
|
|
18
|
+
|
|
19
|
+
**Cause:** usually an older Node.js or pnpm. The SDK needs Node.js 24 or later and pnpm 12.
|
|
20
|
+
|
|
21
|
+
**Fix:** check both, then run the command again:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
node --version
|
|
25
|
+
pnpm --version
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
If pnpm is missing or older, run `corepack enable`, which ships with Node.js, or see [installing pnpm](https://pnpm.io/installation).
|
|
29
|
+
|
|
30
|
+
### `new package` stops with `INSTALL_FAILED`
|
|
31
|
+
|
|
32
|
+
**Symptom:** the package is written, but the command exits with code 5 and `INSTALL_FAILED`.
|
|
33
|
+
|
|
34
|
+
**Cause:** `pnpm install` failed inside the new package, usually on the network or the pnpm version.
|
|
35
|
+
|
|
36
|
+
**Fix:** the files are all there. Fix the cause the install printed, then run `pnpm install` in the package yourself.
|
|
37
|
+
|
|
38
|
+
### A command fails with `PROMPT_REQUIRED`
|
|
39
|
+
|
|
40
|
+
**Symptom:** in a script, a CI job, or an AI agent's terminal, a command exits with code 2 and `PROMPT_REQUIRED`.
|
|
41
|
+
|
|
42
|
+
**Cause:** the command would have asked a question, and there is no terminal to ask in.
|
|
43
|
+
|
|
44
|
+
**Fix:** pass the answer instead: a definition as an argument, with `--file`, or on stdin, and `--yes` to `delete`. [For AI agents](./ai-agents.md) shows each form.
|
|
45
|
+
|
|
12
46
|
## Dev server and sessions
|
|
13
47
|
|
|
14
48
|
### The dev server does not start
|
|
@@ -514,9 +548,9 @@ Exporting only one of the pair fails the same way, naming the other: _'does not
|
|
|
514
548
|
|
|
515
549
|
### The build rejects a teamless surface calling a team-scoped endpoint
|
|
516
550
|
|
|
517
|
-
**Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI
|
|
551
|
+
**Symptom:** `pnpm run sdk build` fails with _'calls endpoint X, which is team-scoped, but this surface has no team of its own'_ on a session UI or setup screen.
|
|
518
552
|
|
|
519
|
-
**Cause:** an endpoint declares whether it acts on one team or on the session, and `scope` is `'team'` when absent. A session UI
|
|
553
|
+
**Cause:** an endpoint declares whether it acts on one team or on the session, and `scope` is `'team'` when absent. A session UI and a setup screen have no team of their own, so there is nothing for a team-scoped call to act against.
|
|
520
554
|
|
|
521
555
|
**Fix:**
|
|
522
556
|
|
|
@@ -533,6 +567,14 @@ Exporting only one of the pair fails the same way, naming the other: _'does not
|
|
|
533
567
|
pnpm run sdk endpoint list
|
|
534
568
|
```
|
|
535
569
|
|
|
570
|
+
### The build rejects an endpoint on the scenario editor
|
|
571
|
+
|
|
572
|
+
**Symptom:** `pnpm run sdk build` fails with `EDITOR_ENDPOINT_NOT_SCENARIO`: _'Scenario Editor "scenario_editor" calls endpoint X, which is session-scoped'_. An editor that built under 1.0 now fails.
|
|
573
|
+
|
|
574
|
+
**Cause:** the scenario editor writes a scenario with no session, so it calls only scenario-scoped endpoints, which are handed the draft's settings and nothing of game state. A session-scoped endpoint there used to be answered with an empty, made-up session.
|
|
575
|
+
|
|
576
|
+
**Fix:** declare the endpoint `"scope": "scenario"`, regenerate its types with `pnpm run sdk generate`, and drop any use of `context`, `participants` or `session` from its handler, which the generated `Handler` type no longer offers. If it declares `reads`, `writes`, `actions` or `roster`, remove them too (`SCENARIO_ENDPOINT_STATEFUL`). See [Scenario-scoped endpoints](./guides/endpoints.md#scenario-scoped-endpoints).
|
|
577
|
+
|
|
536
578
|
### The build is slow
|
|
537
579
|
|
|
538
580
|
**Symptom:** `pnpm run build` takes a long time.
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
* translate the keyword rather than invent a second model.
|
|
19
19
|
*/
|
|
20
20
|
import type { JSONSchema7 } from 'json-schema';
|
|
21
|
+
import type { BlobRetention } from '../storage/blob-store';
|
|
21
22
|
export interface BlobFieldSpec {
|
|
22
23
|
/** Media types, `type/*` wildcards allowed. Absent means any. */
|
|
23
24
|
accept?: string[];
|
|
@@ -25,10 +26,11 @@ export interface BlobFieldSpec {
|
|
|
25
26
|
}
|
|
26
27
|
/** What the resolver needs from a blob store. */
|
|
27
28
|
export interface BlobInputStore {
|
|
28
|
-
/** The stored blob's type and
|
|
29
|
+
/** The stored blob's type, size and retention, or undefined when there is none. */
|
|
29
30
|
describe(id: string): Promise<{
|
|
30
31
|
mimeType: string;
|
|
31
32
|
size: number;
|
|
33
|
+
retention: BlobRetention;
|
|
32
34
|
} | undefined>;
|
|
33
35
|
store(data: Uint8Array, name: string, mimeType: string): Promise<string>;
|
|
34
36
|
}
|
|
@@ -38,6 +40,7 @@ export interface BlobInputStore {
|
|
|
38
40
|
* doing it: past this, a caller uploads first and sends the reference.
|
|
39
41
|
*/
|
|
40
42
|
export declare const MAX_INLINE_BYTES: number;
|
|
43
|
+
export declare function accepts(spec: BlobFieldSpec, mimeType: string): boolean;
|
|
41
44
|
/**
|
|
42
45
|
* The type the bytes say they are, for the handful of formats a game commonly
|
|
43
46
|
* takes, or undefined for anything else. A caller's claimed type is checked
|
|
@@ -54,4 +57,6 @@ export declare function sniffMimeType(data: Uint8Array): string | undefined;
|
|
|
54
57
|
* by the schema or by the handler, leaves its upload behind. That is the same
|
|
55
58
|
* as a surface that uploads and then never submits, and retention clears both.
|
|
56
59
|
*/
|
|
57
|
-
export declare function resolveBlobInputs(identifier: string, schema: JSONSchema7 | undefined, request: unknown, store: BlobInputStore
|
|
60
|
+
export declare function resolveBlobInputs(identifier: string, schema: JSONSchema7 | undefined, request: unknown, store: BlobInputStore, options?: {
|
|
61
|
+
draft?: boolean;
|
|
62
|
+
}): Promise<unknown>;
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
* injected accessors, so it always sees current state without owning it.
|
|
12
12
|
*/
|
|
13
13
|
import type { ResolvedPackageManifest, SDKGame, SDKScenario } from '@seriousgaming/sdk';
|
|
14
|
+
import type { JSONSchema7 } from 'json-schema';
|
|
14
15
|
import type { ResolvedSettings } from './configuration-builder';
|
|
15
16
|
import type { SessionSettingsOverrides, ExecutorDependencies } from './types';
|
|
16
17
|
/** The layered-config state the resolver needs from the executor. */
|
|
@@ -125,3 +126,12 @@ export declare class ConfigResolver {
|
|
|
125
126
|
*/
|
|
126
127
|
saveGameConfiguration(): Promise<void>;
|
|
127
128
|
}
|
|
129
|
+
/**
|
|
130
|
+
* Extract default values declared in a settings schema's properties.
|
|
131
|
+
*/
|
|
132
|
+
/**
|
|
133
|
+
* Layer the settings defaults, a scenario's overrides and a top layer (§8.2),
|
|
134
|
+
* with no session and no executor. What the build judges a scenario against.
|
|
135
|
+
*/
|
|
136
|
+
export declare function resolveSettingsLayers(config: Pick<ResolvedPackageManifest, 'settings'>, scenarioSettings: SessionSettingsOverrides | null, overrides: SessionSettingsOverrides | null): Record<string, Record<string, unknown>>;
|
|
137
|
+
export declare function applySchemaDefaults(configSchema: JSONSchema7 | undefined): Record<string, unknown>;
|
|
@@ -31,7 +31,8 @@ export interface EndpointCallArgs {
|
|
|
31
31
|
}[];
|
|
32
32
|
team?: TeamInfo;
|
|
33
33
|
scopedTeamIndex?: number;
|
|
34
|
-
session
|
|
34
|
+
/** Where the session stands. Absent on a scenario-scoped call, which has none. */
|
|
35
|
+
session?: EndpointSession;
|
|
35
36
|
/**
|
|
36
37
|
* When the call started (`meta.now`, §10.2). The host takes it once, so
|
|
37
38
|
* `Plan` and `Respond` read the same instant. Read from the executor's
|
|
@@ -50,6 +51,12 @@ export interface EndpointCallArgs {
|
|
|
50
51
|
* declared ones. The session's when absent.
|
|
51
52
|
*/
|
|
52
53
|
settings?: Record<string, Record<string, unknown>>;
|
|
54
|
+
/**
|
|
55
|
+
* `meta.scenarioName`, where the call is answered as a scenario other than
|
|
56
|
+
* the session's: the scenario editor's, which is the one being edited
|
|
57
|
+
* (§6.12). The session's when absent.
|
|
58
|
+
*/
|
|
59
|
+
scenarioName?: string | null;
|
|
53
60
|
}
|
|
54
61
|
/**
|
|
55
62
|
* One endpoint call's outcome: the response its caller receives, and, for an
|
|
@@ -8,6 +8,7 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import type { PastStateEntry, SDKGame, SignatureCallbacks } from '@seriousgaming/sdk';
|
|
10
10
|
import { TtsClient } from '../services/tts/client';
|
|
11
|
+
import { type BlobRetention } from '../storage/blob-store';
|
|
11
12
|
import { DocumentParserClient } from '../utils/document-parser-client';
|
|
12
13
|
import { LLMClient } from '../utils/llm-client';
|
|
13
14
|
export interface ExecutorCallbacksDeps {
|
|
@@ -48,6 +49,12 @@ export interface ExecutorCallbacksDeps {
|
|
|
48
49
|
takePlatformFailure?: (() => {
|
|
49
50
|
reason?: string;
|
|
50
51
|
} | undefined) | null;
|
|
52
|
+
/**
|
|
53
|
+
* The retention every blob these callbacks store takes, whatever a
|
|
54
|
+
* `writeBlob` call asks for. Set on a scenario-scoped endpoint's calls,
|
|
55
|
+
* whose files belong to the draft rather than a session (§6.12, §16.2).
|
|
56
|
+
*/
|
|
57
|
+
blobRetention?: BlobRetention;
|
|
51
58
|
}
|
|
52
59
|
/**
|
|
53
60
|
* Build the raw callbacks object. Constructed fresh per resource invocation so
|
|
@@ -86,6 +86,17 @@ export declare class GameExecutor {
|
|
|
86
86
|
*/
|
|
87
87
|
setRunKind(kind: RunKind): void;
|
|
88
88
|
getRunKind(): RunKind;
|
|
89
|
+
/**
|
|
90
|
+
* The active scenario's name in the session locale, or null when the
|
|
91
|
+
* session runs on the game's own settings. Logic reads it as
|
|
92
|
+
* `meta.scenarioName`.
|
|
93
|
+
*/
|
|
94
|
+
getScenarioName(): string | null;
|
|
95
|
+
/**
|
|
96
|
+
* A scenario's display name in the session locale, falling back through
|
|
97
|
+
* what it declares (§18.2), or null for none.
|
|
98
|
+
*/
|
|
99
|
+
scenarioNameOf(scenario: SDKScenario | null | undefined): string | null;
|
|
89
100
|
/**
|
|
90
101
|
* Where the roster logic receives as `participants` comes from (§10.2).
|
|
91
102
|
*
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
* own copy and drifting.
|
|
12
12
|
*/
|
|
13
13
|
import type { ApiUse, ResolvedPackageManifest, LogicMeta, Participant, RunKind, RunMeta, SignatureCallbacks } from '@seriousgaming/sdk';
|
|
14
|
+
import type { BlobRetention } from '../storage/blob-store';
|
|
14
15
|
import { type ExecutorCallbacksDeps } from './executor-callbacks';
|
|
15
16
|
import { type LogicOrigin, type SourceMapRegistry } from './logic-failure';
|
|
16
17
|
import type { LogicKind, LogicResource } from './logic-loader';
|
|
@@ -54,6 +55,12 @@ export interface LogicCallsOptions {
|
|
|
54
55
|
deps: Pick<ExecutorDependencies, 'logicExecutionBoundMs' | 'tickExecutionBoundMs'>;
|
|
55
56
|
/** The loaded bundles' source maps, to read a thrown stack back to source. */
|
|
56
57
|
sourceMaps: SourceMapRegistry;
|
|
58
|
+
/**
|
|
59
|
+
* The active scenario's name in the session locale, surfaced as
|
|
60
|
+
* `meta.scenarioName`. Read on every call rather than held, so it follows a
|
|
61
|
+
* locale change or a scenario switch without anybody remembering to set it.
|
|
62
|
+
*/
|
|
63
|
+
scenarioName: () => string | null;
|
|
57
64
|
/** What the raw callbacks are built from, less what this class supplies. */
|
|
58
65
|
callbacks: Omit<ExecutorCallbacksDeps, 'readPastState' | 'getScopedTeamIndexes' | 'getAllTeamIndexes' | 'takePlatformFailure'>;
|
|
59
66
|
}
|
|
@@ -153,7 +160,7 @@ export declare class LogicCalls {
|
|
|
153
160
|
* fresh so they read the live game, with every one its `uses` does not
|
|
154
161
|
* declare replaced by a throwing stub.
|
|
155
162
|
*/
|
|
156
|
-
callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined): SignatureCallbacks;
|
|
163
|
+
callbacksFor(resourceIdentifier: string, uses: readonly ApiUse[] | undefined, blobRetention?: BlobRetention): SignatureCallbacks;
|
|
157
164
|
/**
|
|
158
165
|
* Bound one call into author logic that runs as part of a tick, or of the
|
|
159
166
|
* initialisation a tick starts from (§11.10).
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `Scenario` validator gate: every validator exporting it, put to one
|
|
3
|
+
* scenario, collecting every problem.
|
|
4
|
+
*
|
|
5
|
+
* Unlike the other two gates it needs no session. It judges settings, not a
|
|
6
|
+
* board, so the build can run it on a package's own scenarios and the dev
|
|
7
|
+
* server on a scenario about to be saved, with only the package and a loader.
|
|
8
|
+
*/
|
|
9
|
+
import type { ResolvedPackageManifest, ScenarioProblem } from '@seriousgaming/sdk';
|
|
10
|
+
import { LogicLoader } from './logic-loader';
|
|
11
|
+
import type { SessionSettingsOverrides } from './types';
|
|
12
|
+
/** The `requires` feature name a package using the `Scenario` gate lists (§15.8). */
|
|
13
|
+
export declare const SCENARIO_VALIDATION = "scenario-validation";
|
|
14
|
+
/** A problem one validator found with a scenario. */
|
|
15
|
+
export interface ScenarioGateProblem extends ScenarioProblem {
|
|
16
|
+
validatorIdentifier: string;
|
|
17
|
+
}
|
|
18
|
+
/** Whether any validator in the package gates scenarios. */
|
|
19
|
+
export declare function hasScenarioGate(config: Pick<ResolvedPackageManifest, 'validators'>): boolean;
|
|
20
|
+
/**
|
|
21
|
+
* Put `scenarioSettings` (a scenario's own `settings`, or `null` for a session
|
|
22
|
+
* on no scenario) to every validator exporting `Scenario`, in manifest order.
|
|
23
|
+
* An empty array means the scenario passes.
|
|
24
|
+
*/
|
|
25
|
+
export declare function runScenarioGates(options: {
|
|
26
|
+
packagePath: string;
|
|
27
|
+
config: ResolvedPackageManifest;
|
|
28
|
+
scenarioSettings: SessionSettingsOverrides | null;
|
|
29
|
+
locale?: string;
|
|
30
|
+
loader?: LogicLoader;
|
|
31
|
+
boundMs?: number;
|
|
32
|
+
}): Promise<ScenarioGateProblem[]>;
|
|
33
|
+
/** One line per problem, naming the validator and the setting. */
|
|
34
|
+
export declare function describeScenarioProblems(problems: ScenarioGateProblem[]): string[];
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { SDKFacilitatorGuide } from '@seriousgaming/sdk';
|
|
2
|
+
import { type GuideSettings } from './settings.js';
|
|
3
|
+
/** The guide as one session reads it (§6.13.5). */
|
|
4
|
+
export interface EffectiveGuide {
|
|
5
|
+
identifier: string;
|
|
6
|
+
locales: Record<string, {
|
|
7
|
+
name?: string;
|
|
8
|
+
}>;
|
|
9
|
+
/** Each locale's chapter files, in filename order, without the chapters left empty. */
|
|
10
|
+
chapters: Record<string, string[]>;
|
|
11
|
+
/** The settings the guide declares, resolved for the session. */
|
|
12
|
+
settings: GuideSettings;
|
|
13
|
+
}
|
|
14
|
+
/**
|
|
15
|
+
* Read a guide from `root` as a session with `resolved` settings sees it, or
|
|
16
|
+
* null when no chapter is left to show. Whether a chapter is shown is decided
|
|
17
|
+
* on its reference-locale file, so a translation cannot show a chapter its
|
|
18
|
+
* original hides.
|
|
19
|
+
*/
|
|
20
|
+
export declare function readEffectiveGuide(guide: SDKFacilitatorGuide, root: string, resolved: GuideSettings): EffectiveGuide | null;
|
package/dist/guide/locale.d.ts
CHANGED
|
@@ -10,3 +10,15 @@
|
|
|
10
10
|
* locale).
|
|
11
11
|
*/
|
|
12
12
|
export declare function referenceLocale(locales: Record<string, unknown>): string;
|
|
13
|
+
/** A chapter, and the locale its file is read from. */
|
|
14
|
+
export interface ChapterSource {
|
|
15
|
+
file: string;
|
|
16
|
+
locale: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* The guide's chapters as a reader of `requested` sees them: the reference
|
|
20
|
+
* locale's chapter set, in its order, each read from the first locale in the
|
|
21
|
+
* §18.2 chain that has it (requested, then 'en', then the first declared).
|
|
22
|
+
* A chapter whose `locale` differs from `requested` is untranslated (§6.13.4).
|
|
23
|
+
*/
|
|
24
|
+
export declare function chapterSources(locales: Record<string, unknown>, chapters: Record<string, string[]>, requested: string): ChapterSource[];
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { Root } from 'mdast';
|
|
2
|
+
/**
|
|
3
|
+
* Settings in facilitator guide markdown (§6.13.5).
|
|
4
|
+
*
|
|
5
|
+
* A guide that declares `settings` may show a resolved value inline with
|
|
6
|
+
* `:setting[identifier.path]`, and show or hide a block with
|
|
7
|
+
* `:::when{setting="identifier.path" is="value" not}`. Both are evaluated on
|
|
8
|
+
* the parsed tree before anything renders, so a value can never introduce
|
|
9
|
+
* markup, and a chapter left with nothing to show is dropped from the guide.
|
|
10
|
+
*
|
|
11
|
+
* This module is browser-safe: the dev console renders with it, the build
|
|
12
|
+
* validates with it, and `@seriousgaming/sdk-tools/host` exports it so a
|
|
13
|
+
* platform evaluates exactly as the dev server does.
|
|
14
|
+
*/
|
|
15
|
+
/** Resolved settings, keyed by settings identifier, as a resource receives them. */
|
|
16
|
+
export type GuideSettings = Record<string, Record<string, unknown>>;
|
|
17
|
+
/** The attributes `:::when` accepts. Anything else is refused by the build. */
|
|
18
|
+
export declare const WHEN_ATTRIBUTES: readonly ["setting", "is", "not"];
|
|
19
|
+
/** A setting a chapter names, where it names it, for the build to check. */
|
|
20
|
+
export interface SettingReference {
|
|
21
|
+
kind: 'value' | 'when';
|
|
22
|
+
/** `identifier.path`, as written. */
|
|
23
|
+
path: string;
|
|
24
|
+
line: number;
|
|
25
|
+
/** `when` only: the literal `is` compares against, if any. */
|
|
26
|
+
is?: string;
|
|
27
|
+
/** Attributes the grammar does not define, as written. */
|
|
28
|
+
unknownAttributes: string[];
|
|
29
|
+
/** `when` only: true when it sits inside another `when`. */
|
|
30
|
+
nested: boolean;
|
|
31
|
+
}
|
|
32
|
+
type Lookup = {
|
|
33
|
+
found: true;
|
|
34
|
+
value: unknown;
|
|
35
|
+
} | {
|
|
36
|
+
found: false;
|
|
37
|
+
};
|
|
38
|
+
/** The value at `identifier.key.key…` in resolved settings. */
|
|
39
|
+
export declare function lookupSetting(settings: GuideSettings, path: string): Lookup;
|
|
40
|
+
/** How a value reads in the guide, or null when it is not a renderable kind. */
|
|
41
|
+
export declare function formatSettingValue(value: unknown, locale: string): string | null;
|
|
42
|
+
/** Whether a `:::when` shows its content, or an error when it cannot be decided. */
|
|
43
|
+
export declare function evaluateWhen(settings: GuideSettings, attributes: Record<string, string | null | undefined>): {
|
|
44
|
+
show: boolean;
|
|
45
|
+
} | {
|
|
46
|
+
error: string;
|
|
47
|
+
};
|
|
48
|
+
/**
|
|
49
|
+
* Remark plugin evaluating `:setting` and `:::when` against resolved settings.
|
|
50
|
+
* Runs after `remark-directive` and before the guide's own directive handling,
|
|
51
|
+
* which would otherwise render `when` as an unknown admonition and restore
|
|
52
|
+
* `:setting` to its literal text.
|
|
53
|
+
*/
|
|
54
|
+
export declare function remarkGuideSettings(options: {
|
|
55
|
+
settings: GuideSettings;
|
|
56
|
+
locale: string;
|
|
57
|
+
}): (tree: Root) => void;
|
|
58
|
+
/** A chapter's tree with its settings evaluated. */
|
|
59
|
+
export declare function evaluateChapter(markdown: string, settings: GuideSettings, locale: string): Root;
|
|
60
|
+
/**
|
|
61
|
+
* Whether a chapter has nothing to show once its settings are evaluated. Such
|
|
62
|
+
* a chapter is left out of the guide, table of contents included (§6.13.5).
|
|
63
|
+
*/
|
|
64
|
+
export declare function isChapterEmpty(markdown: string, settings: GuideSettings): boolean;
|
|
65
|
+
/** Every setting a chapter names, for the build to check against the declared schemas. */
|
|
66
|
+
export declare function settingReferences(markdown: string): SettingReference[];
|
|
67
|
+
export {};
|
|
@@ -101,8 +101,17 @@ export interface HostChannelOptions {
|
|
|
101
101
|
handshakeTimeoutMs?: number;
|
|
102
102
|
/** Guest messages the channel does not answer itself. */
|
|
103
103
|
onMessage?(message: GuestMessage): void;
|
|
104
|
-
/**
|
|
105
|
-
|
|
104
|
+
/**
|
|
105
|
+
* Called each time the handshake completes, reconnections included.
|
|
106
|
+
* `signalsRendered` says the guest announced it will send `rendered`
|
|
107
|
+
* (§12.5), so a host may keep its own loading screen up until
|
|
108
|
+
* {@link onRendered}; a guest that did not announce it is ready to show now.
|
|
109
|
+
*/
|
|
110
|
+
onConnect?(handshake: {
|
|
111
|
+
signalsRendered: boolean;
|
|
112
|
+
}): void;
|
|
113
|
+
/** Called each time the guest reports its first paint on screen (§12.5). */
|
|
114
|
+
onRendered?(): void;
|
|
106
115
|
/** Called when the channel gives up on the frame. */
|
|
107
116
|
onTeardown?(reason: TeardownReason): void;
|
|
108
117
|
/** Where diagnostics go. Defaults to `console`. */
|
package/dist/host/index.d.ts
CHANGED
|
@@ -10,6 +10,10 @@
|
|
|
10
10
|
* supplies, and the host's definition of the wire messages. The guest half is
|
|
11
11
|
* the UI wrappers in `@seriousgaming/sdk/ui`. The shapes
|
|
12
12
|
* may change in a minor release.
|
|
13
|
+
*
|
|
14
|
+
* It also carries how the host reads a facilitator guide (§6.13): which locale
|
|
15
|
+
* each chapter is read from, and how settings in its markdown evaluate, so a
|
|
16
|
+
* platform shows exactly the guide the dev server shows.
|
|
13
17
|
*/
|
|
14
18
|
export { HostChannel } from './host-channel.js';
|
|
15
19
|
export type { FrameLike, GuestMessage, HostChannelOptions, HostMessage, TeardownReason, WindowLike, } from './host-channel.js';
|
|
@@ -17,4 +21,6 @@ export type { HostAdapter, RequestOrigin } from './adapter.js';
|
|
|
17
21
|
export { isPlayerSurface, requiredMessagesFor, SURFACES, type SurfaceDescriptor, type SurfaceKind, } from './surfaces.js';
|
|
18
22
|
export { UI_PROTOCOL_VERSION } from './protocol.js';
|
|
19
23
|
export type { AssetUrls, HostSettingsEditorPortMessage, HostPortMessage, HostPresentationPortMessage, HostSessionPortMessage, HostWindowMessage, IFrameSettingsEditorPortMessage, IFrameMessage, IFramePortMessage, IFramePresentationPortMessage, IFrameSessionPortMessage, } from './protocol.js';
|
|
20
|
-
export { contrastTextFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';
|
|
24
|
+
export { contrastTextFor, neutralsFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';
|
|
25
|
+
export { chapterSources, referenceLocale, type ChapterSource } from '../guide/locale.js';
|
|
26
|
+
export { evaluateChapter, evaluateWhen, formatSettingValue, isChapterEmpty, lookupSetting, remarkGuideSettings, type GuideSettings, } from '../guide/settings.js';
|
package/dist/host/protocol.d.ts
CHANGED
|
@@ -56,6 +56,13 @@ export declare const UI_PROTOCOL_VERSION = 4;
|
|
|
56
56
|
export type IFrameMessage = {
|
|
57
57
|
type: 'ready';
|
|
58
58
|
protocolVersion: number;
|
|
59
|
+
/**
|
|
60
|
+
* The surface will send `rendered` once its first paint is on screen, so a
|
|
61
|
+
* host may keep its own loading screen over the frame until then (§12.5).
|
|
62
|
+
* Absent from a surface built before the signal existed, which a host shows
|
|
63
|
+
* as soon as it connects, as it always did.
|
|
64
|
+
*/
|
|
65
|
+
signalsRendered?: true;
|
|
59
66
|
};
|
|
60
67
|
/**
|
|
61
68
|
* Window-level message: host → iframe. Carries port2 as a transfer.
|
|
@@ -133,6 +140,19 @@ export type HostPortMessage = {
|
|
|
133
140
|
| {
|
|
134
141
|
type: 'setRunKind';
|
|
135
142
|
runKind: RunKind;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The active scenario's name in the session locale, or `null` when the
|
|
146
|
+
* session runs on the game's own settings. For display only (§6.15.1).
|
|
147
|
+
* Sent in the initial batch and again whenever it changes, with a locale
|
|
148
|
+
* change or a scenario switch.
|
|
149
|
+
*
|
|
150
|
+
* The wrapper's `null` default is a fallback for a host predating this
|
|
151
|
+
* message, which a surface already has to render (§12.3).
|
|
152
|
+
*/
|
|
153
|
+
| {
|
|
154
|
+
type: 'setScenarioName';
|
|
155
|
+
scenarioName: string | null;
|
|
136
156
|
} | {
|
|
137
157
|
type: 'setTimer';
|
|
138
158
|
payload: TimerState;
|
|
@@ -253,6 +273,10 @@ export type HostPortMessage = {
|
|
|
253
273
|
/** Port messages sent from game UI iframe to host */
|
|
254
274
|
export type IFramePortMessage = {
|
|
255
275
|
type: 'pong';
|
|
276
|
+
}
|
|
277
|
+
/** First paint is on screen, after the handshake that announced it (§12.5). */
|
|
278
|
+
| {
|
|
279
|
+
type: 'rendered';
|
|
256
280
|
} | {
|
|
257
281
|
type: 'updateData';
|
|
258
282
|
requestId?: string;
|
|
@@ -383,6 +407,14 @@ export type HostSessionPortMessage = {
|
|
|
383
407
|
type: 'setRunKind';
|
|
384
408
|
runKind: RunKind;
|
|
385
409
|
}
|
|
410
|
+
/**
|
|
411
|
+
* The active scenario's name in the session locale, or `null`. For
|
|
412
|
+
* display only (§6.15.1); sent as a game UI's is.
|
|
413
|
+
*/
|
|
414
|
+
| {
|
|
415
|
+
type: 'setScenarioName';
|
|
416
|
+
scenarioName: string | null;
|
|
417
|
+
}
|
|
386
418
|
/**
|
|
387
419
|
* Where to open the walkthrough run (§5.7). Every host offers one, so this
|
|
388
420
|
* always carries a link. Facilitator-only, and naming no team: a
|
|
@@ -473,6 +505,10 @@ export type HostSessionPortMessage = {
|
|
|
473
505
|
/** Port messages sent from session UI iframe to host */
|
|
474
506
|
export type IFrameSessionPortMessage = {
|
|
475
507
|
type: 'pong';
|
|
508
|
+
}
|
|
509
|
+
/** First paint is on screen, after the handshake that announced it (§12.5). */
|
|
510
|
+
| {
|
|
511
|
+
type: 'rendered';
|
|
476
512
|
} | {
|
|
477
513
|
type: 'updateSessionData';
|
|
478
514
|
requestId?: string;
|
|
@@ -579,11 +615,11 @@ export type IFrameSessionPortMessage = {
|
|
|
579
615
|
}
|
|
580
616
|
/**
|
|
581
617
|
* Ask the host to open one of its own overlays (§6.4). The host renders it;
|
|
582
|
-
* this delegates the trigger alone. `target` is
|
|
583
|
-
*
|
|
584
|
-
*
|
|
585
|
-
*
|
|
586
|
-
*
|
|
618
|
+
* this delegates the trigger alone. `target` is a team id for
|
|
619
|
+
* `print-sheets`, and omitting it means every team. `facilitator-guide`
|
|
620
|
+
* takes none: a game holds one guide, and a `target` is ignored. An overlay
|
|
621
|
+
* the host does not offer, or a team id not in the session, settles as
|
|
622
|
+
* denied.
|
|
587
623
|
*/
|
|
588
624
|
| {
|
|
589
625
|
type: 'openHostOverlay';
|
|
@@ -686,6 +722,10 @@ export type HostSettingsEditorPortMessage = {
|
|
|
686
722
|
*/
|
|
687
723
|
export type IFrameSettingsEditorPortMessage = {
|
|
688
724
|
type: 'pong';
|
|
725
|
+
}
|
|
726
|
+
/** First paint is on screen, after the handshake that announced it (§12.5). */
|
|
727
|
+
| {
|
|
728
|
+
type: 'rendered';
|
|
689
729
|
} | {
|
|
690
730
|
type: 'updateSettings';
|
|
691
731
|
requestId?: string;
|
|
@@ -767,6 +807,10 @@ export type HostPresentationPortMessage = {
|
|
|
767
807
|
/** Port messages sent from presentation iframe to host. Reads only. */
|
|
768
808
|
export type IFramePresentationPortMessage = {
|
|
769
809
|
type: 'pong';
|
|
810
|
+
}
|
|
811
|
+
/** First paint is on screen, after the handshake that announced it (§12.5). */
|
|
812
|
+
| {
|
|
813
|
+
type: 'rendered';
|
|
770
814
|
} | {
|
|
771
815
|
type: 'refreshAssetAuth:response';
|
|
772
816
|
requestId: string;
|
package/dist/host/theme.d.ts
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
* Platform-facing: exported from
|
|
11
11
|
* `@seriousgaming/sdk-tools/host`.
|
|
12
12
|
*/
|
|
13
|
-
import type { ThemeColorRole, ThemeContrastText, UserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
13
|
+
import type { Brand, ThemeColorRole, ThemeContrastText, UserInterfaceTheme } from '@seriousgaming/sdk/ui';
|
|
14
14
|
/** The roles a theme sends, in the order §12.3 lists them. */
|
|
15
15
|
export declare const THEME_COLOR_ROLES: readonly ThemeColorRole[];
|
|
16
16
|
/** The WCAG AA minimum for normal text. */
|
|
@@ -40,16 +40,42 @@ export declare function contrastTextFor(colour: string, preferred?: string): str
|
|
|
40
40
|
/** One mode's colours before a host has given them their text colours. */
|
|
41
41
|
export type ModeColoursInput = Record<ThemeColorRole, string> & {
|
|
42
42
|
contrastText?: Partial<ThemeContrastText>;
|
|
43
|
+
/**
|
|
44
|
+
* The page colour, raised surfaces, and the author's text for both
|
|
45
|
+
* (§12.3). Optional here, because a host can always send a plain page's:
|
|
46
|
+
* the payload carries all three either way.
|
|
47
|
+
*/
|
|
48
|
+
background?: string;
|
|
49
|
+
surface?: string;
|
|
50
|
+
text?: string;
|
|
43
51
|
};
|
|
44
52
|
/** A theme before a host has given its colours their text colours. */
|
|
45
53
|
export interface ThemeInput {
|
|
46
54
|
mode: 'light' | 'dark';
|
|
47
55
|
light: ModeColoursInput;
|
|
48
56
|
dark: ModeColoursInput;
|
|
57
|
+
/** The host's brand, sent as it is (§12.3). */
|
|
58
|
+
brand: Brand;
|
|
49
59
|
}
|
|
60
|
+
type Neutrals = {
|
|
61
|
+
background: string;
|
|
62
|
+
surface: string;
|
|
63
|
+
text: string;
|
|
64
|
+
};
|
|
65
|
+
/**
|
|
66
|
+
* The author's page, surface and text colours, made fit to send, or undefined
|
|
67
|
+
* when they cannot be (§12.3).
|
|
68
|
+
*
|
|
69
|
+
* `text` is held to 4.5:1 or better against both of the others: the author's
|
|
70
|
+
* own where it meets that, otherwise black or white, whichever does better
|
|
71
|
+
* against the weaker of the two. Where neither can, the pair cannot carry text,
|
|
72
|
+
* and the caller sends a plain page instead.
|
|
73
|
+
*/
|
|
74
|
+
export declare function neutralsFor(colours: Partial<Neutrals>): Neutrals | undefined;
|
|
50
75
|
/**
|
|
51
76
|
* The `setTheme` payload for a theme: every colour of both modes given its
|
|
52
|
-
* `contrastText`, keeping any the author supplied that meet AA
|
|
77
|
+
* `contrastText`, keeping any the author supplied that meet AA, page colours
|
|
78
|
+
* that carry text (the author's, or a plain page's), and the brand as it is.
|
|
53
79
|
*/
|
|
54
80
|
export declare function withContrastText(theme: ThemeInput): UserInterfaceTheme;
|
|
55
81
|
export {};
|