@cratis/pi 7.64.0 → 7.66.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 (47) hide show
  1. package/package/corpus/product-sync.json +4 -4
  2. package/package/corpus/skills/cratis-fundamentals-concept/references/shop-generation.md +16 -3
  3. package/package/corpus/skills/cratis-screenplay-automations-and-translations/SKILL.md +2 -1
  4. package/package/corpus/skills/cratis-screenplay-captures-and-reactions/SKILL.md +3 -1
  5. package/package/corpus/skills/cratis-screenplay-command-surface/SKILL.md +2 -1
  6. package/package/corpus/skills/cratis-screenplay-command-surface/references/generated-values-and-responses.md +30 -0
  7. package/package/corpus/skills/cratis-screenplay-command-surface/references/protected-reads.md +15 -5
  8. package/package/corpus/skills/cratis-screenplay-event-modeling/SKILL.md +2 -2
  9. package/package/corpus/skills/cratis-screenplay-event-modeling/references/parsed-not-runnable.md +1 -1
  10. package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/generated-recovery.md +14 -2
  11. package/package/corpus/skills/cratis-screenplay-model-authoring/references/language-reference.md +1 -1
  12. package/package/corpus/skills/cratis-screenplay-model-authoring/references/mcp-tools.md +2 -2
  13. package/package/corpus/skills/cratis-screenplay-model-authoring/references/screen-authoring-workflow.md +13 -0
  14. package/package/corpus/skills/cratis-screenplay-model-review/references/anti-patterns.md +1 -1
  15. package/package/corpus/skills/cratis-screenplay-model-review/references/checklist.md +1 -1
  16. package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/principles.md +1 -1
  17. package/package/corpus/skills/cratis-screenplay-modeling-lifecycle/references/vocabulary-map.md +1 -1
  18. package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/SKILL.md +3 -2
  19. package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/gap-fill-handoff.md +3 -1
  20. package/package/corpus/skills/cratis-screenplay-render-and-gap-fill/references/renderability-gate.md +6 -1
  21. package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/berth-reservations.md +1 -1
  22. package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/invoicing-dues-design.md +1 -1
  23. package/package/corpus/skills/cratis-screenplay-scenario-coverage/references/spec-forms-by-mode.md +1 -1
  24. package/package/corpus/skills/cratis-screenplay-slice-design/references/rule-layers.md +1 -1
  25. package/package/corpus/skills/cratis-screenplay-slice-design/references/worked-example.md +1 -1
  26. package/package/corpus/skills/cratis-screenplay-streams-and-consistency/SKILL.md +1 -1
  27. package/package/corpus/skills/cratis-screenplay-streams-and-consistency/references/consistency-and-concurrency.md +3 -2
  28. package/package/corpus/skills/cratis-screenplay-streams-and-consistency/references/streams-example.md +1 -1
  29. package/package/corpus/skills/cratis-screenplay-toolchain/references/diagnostic-arguments.md +7 -0
  30. package/package/corpus/skills/cratis-screenplay-toolchain/references/diagnostics.md +26 -2
  31. package/package/corpus/skills/cratis-screenplay-toolchain/references/language-admission.md +5 -3
  32. package/package/corpus/skills/cratis-screenplay-toolchain/references/preferred-syntax.md +2 -1
  33. package/package/corpus/skills/cratis-screenplay-toolchain/references/renderable-subset.md +4 -2
  34. package/package/corpus/skills/cratis-screenplay-toolchain/references/screenplay-contract.json +308 -0
  35. package/package/corpus/skills/cratis-screenplay-toolchain/references/screenplay-contract.version +1 -1
  36. package/package/corpus/skills/cratis-screenplay-toolchain/references/traps.md +1 -1
  37. package/package/corpus/skills/cratis-screenplay-ui-composition/SKILL.md +4 -3
  38. package/package/corpus/skills/cratis-screenplay-ui-composition/references/application-shell.md +1 -1
  39. package/package/corpus/skills/cratis-screenplay-ui-composition/references/screen-composition-contract.md +1 -1
  40. package/package/corpus/skills/cratis-screenplay-ui-composition/references/ui-profile-and-theme.md +124 -2
  41. package/package/corpus/skills/cratis-screenplay-ui-composition/verification.json +25 -0
  42. package/package/corpus/skills/cratis-stage-rendering-and-sandbox/SKILL.md +12 -4
  43. package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/admission.md +5 -3
  44. package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/rendered-application.md +41 -1
  45. package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/sandbox-and-specrunner.md +32 -1
  46. package/package/corpus/skills/cratis-stage-rendering-and-sandbox/references/scene-runtime.md +10 -0
  47. package/package.json +1 -1
@@ -5,7 +5,7 @@
5
5
 
6
6
  Use these forms when writing or reviewing `.play`. Acceptance of an older
7
7
  spelling is not a recommendation to teach it. Information diagnostics do not
8
- fail `--warnaserror`; the corpus verification gate rejects the eleven style codes
8
+ fail `--warnaserror`; the corpus verification gate rejects the twelve style codes
9
9
  below even when a fence declares `expect`, unless an exact, reasoned migration
10
10
  exception exists in the verifier's preferred-syntax allowlist. That allowlist also
11
11
  covers deliberate legacy explanations in prose; stale entries fail.
@@ -24,6 +24,7 @@ covers deliberate legacy explanations in prose; stale entries fail.
24
24
  | Interaction guard | Block-form `when` alternatives | Opaque interaction `where` on click, double click or select | PLAY0564 (warning or information) |
25
25
  | Projection transition cardinality | Source binding emits `One` | Constructed/deserialized ESM v1–v3 `ZeroOrOne` / `Many` | PLAY0445 (warning; ESM-only, not a source spelling) |
26
26
  | Command decision reads | `command reads protected` after reviewing every read's admission, absence and conflict semantics | Eligible legacy command reads without the application-root preamble | PLAY0786 (information; individual typed repair review, never fix-all) |
27
+ | Profile shell | `root template <Name>` in a `ui profile` | `layout <Name>` in a `ui profile` | PLAY0791 (warning; quick fix) |
27
28
  | Literal text rules | `starts with`, `ends with`, `contains`, `not contains` or equality, preserving message and severity | Exact deprecated Studio `matches` shapes | PLAY0787 (warning; not arbitrary regex rewriting) |
28
29
 
29
30
  `query Q => observable?` is not a legacy optional type suffix and has no keyword
@@ -60,12 +60,14 @@ This table is a reading of the renderer's admission, not a render result: run th
60
60
  | Evolved events | initial revisions only (migrations are not rendered) | `STAGE-ESM-026` |
61
61
  | Descriptions, documentation | XML `<summary>`/`<remarks>` doc comments only | characters invalid in XML: `CLI-RENDER-005`; never behavior |
62
62
 
63
- Stage refuses protected command reads with STAGE-ESM-044, described handlers
63
+ The Cratis C# renderer refuses protected command reads with STAGE-ESM-044, described handlers
64
64
  with STAGE-IMPL-002 (even Stub mode), and atomic mode in admitted pairs with
65
65
  STAGE-ESM-043. Literal
66
66
  text rules execute/render ordinal UTF-16 comparisons. Read [language admission](language-admission.md).
67
67
  A CLI's older bundled compiler may fail first: legacy reads/concurrency PLAY0271,
68
- attached handlers PLAY0268. Protected reads bind standalone v25, not a Stage render.
68
+ attached handlers PLAY0268. Protected reads bind v25, not a Stage render. Requires Stage 4.129.0 for semantic
69
+ Host/executor protected reads; older engines refuse -044. Non-Error protected requirements
70
+ refuse STAGE-ESM-045, including reaction invocations; this is not a rendering result.
69
71
  Response-name authoring scopes are not rendered and Scene runtime does not supply them.
70
72
 
71
73
  Compliance mapping in the generated C#: personal data to `[PII]`, operational secrets to
@@ -79,6 +79,7 @@
79
79
  "count",
80
80
  "criminal",
81
81
  "csharp",
82
+ "dark",
82
83
  "data",
83
84
  "day",
84
85
  "days",
@@ -184,6 +185,7 @@
184
185
  "legalObligation",
185
186
  "legitimateInterests",
186
187
  "length",
188
+ "light",
187
189
  "literal",
188
190
  "load",
189
191
  "locale",
@@ -26070,6 +26072,10 @@
26070
26072
  "minimumSemanticVersion": "1.0",
26071
26073
  "diagnostic": "PLAY0269",
26072
26074
  "diagnostics": [
26075
+ {
26076
+ "code": "PLAY0791",
26077
+ "severity": "warning"
26078
+ },
26073
26079
  {
26074
26080
  "code": "PLAY0720",
26075
26081
  "severity": "warning"
@@ -34238,6 +34244,260 @@
34238
34244
  "reserved": false,
34239
34245
  "retired": false
34240
34246
  },
34247
+ {
34248
+ "code": "PLAY0790",
34249
+ "name": "UnknownRootTemplate",
34250
+ "severity": "error",
34251
+ "severities": [
34252
+ "error"
34253
+ ],
34254
+ "title": "A ui profile\u0027s root template, or its new screens use template default, names an own template the document does not declare.",
34255
+ "reserved": false,
34256
+ "retired": false,
34257
+ "arguments": [
34258
+ {
34259
+ "name": "profile",
34260
+ "kind": "text",
34261
+ "optional": false,
34262
+ "meaning": "The ui profile that names the template."
34263
+ },
34264
+ {
34265
+ "name": "template",
34266
+ "kind": "text",
34267
+ "optional": false,
34268
+ "meaning": "The template name that nothing declares, or the blueprint does not ship."
34269
+ },
34270
+ {
34271
+ "name": "blueprint",
34272
+ "kind": "text",
34273
+ "optional": true,
34274
+ "meaning": "The blueprint a template was expected from."
34275
+ }
34276
+ ]
34277
+ },
34278
+ {
34279
+ "code": "PLAY0791",
34280
+ "name": "LegacyProfileLayout",
34281
+ "severity": "warning",
34282
+ "severities": [
34283
+ "warning"
34284
+ ],
34285
+ "title": "A ui profile selects its shell with the legacy layout line instead of root template.",
34286
+ "reserved": false,
34287
+ "retired": false,
34288
+ "arguments": [
34289
+ {
34290
+ "name": "profile",
34291
+ "kind": "text",
34292
+ "optional": false,
34293
+ "meaning": "The ui profile that uses the legacy \u0060layout\u0060 line."
34294
+ },
34295
+ {
34296
+ "name": "template",
34297
+ "kind": "text",
34298
+ "optional": false,
34299
+ "meaning": "The layout name the line selects."
34300
+ }
34301
+ ]
34302
+ },
34303
+ {
34304
+ "code": "PLAY0792",
34305
+ "name": "UnknownRootBlueprint",
34306
+ "severity": "error",
34307
+ "severities": [
34308
+ "error"
34309
+ ],
34310
+ "title": "A ui profile\u0027s root template, or its new screens use template default, comes from a blueprint the profile does not list in its packages, or one the host\u0027s installed catalog does not contain.",
34311
+ "reserved": false,
34312
+ "retired": false,
34313
+ "arguments": [
34314
+ {
34315
+ "name": "profile",
34316
+ "kind": "text",
34317
+ "optional": false,
34318
+ "meaning": "The ui profile that names the blueprint."
34319
+ },
34320
+ {
34321
+ "name": "template",
34322
+ "kind": "text",
34323
+ "optional": false,
34324
+ "meaning": "The template that was taken from the blueprint."
34325
+ },
34326
+ {
34327
+ "name": "blueprint",
34328
+ "kind": "text",
34329
+ "optional": false,
34330
+ "meaning": "The blueprint the profile does not list or the host has not installed."
34331
+ }
34332
+ ]
34333
+ },
34334
+ {
34335
+ "code": "PLAY0793",
34336
+ "name": "RootTemplateVersionNotSatisfied",
34337
+ "severity": "warning",
34338
+ "severities": [
34339
+ "warning"
34340
+ ],
34341
+ "title": "A ui profile\u0027s root template pins a blueprint version range the installed blueprint does not satisfy.",
34342
+ "reserved": false,
34343
+ "retired": false,
34344
+ "arguments": [
34345
+ {
34346
+ "name": "profile",
34347
+ "kind": "text",
34348
+ "optional": false,
34349
+ "meaning": "The ui profile that names the root template."
34350
+ },
34351
+ {
34352
+ "name": "template",
34353
+ "kind": "text",
34354
+ "optional": false,
34355
+ "meaning": "The root template."
34356
+ },
34357
+ {
34358
+ "name": "blueprint",
34359
+ "kind": "text",
34360
+ "optional": false,
34361
+ "meaning": "The blueprint whose installed version does not satisfy the pin."
34362
+ },
34363
+ {
34364
+ "name": "version",
34365
+ "kind": "text",
34366
+ "optional": false,
34367
+ "meaning": "The version range that is pinned, or the default \u0060^\u0060 pin of the installed version."
34368
+ }
34369
+ ]
34370
+ },
34371
+ {
34372
+ "code": "PLAY0794",
34373
+ "name": "RootTemplateNotApplicable",
34374
+ "severity": "error",
34375
+ "severities": [
34376
+ "error"
34377
+ ],
34378
+ "title": "A ui profile\u0027s root template cannot be the application\u0027s shell: it is not a layout or an application-scope root screen template.",
34379
+ "reserved": false,
34380
+ "retired": false,
34381
+ "arguments": [
34382
+ {
34383
+ "name": "profile",
34384
+ "kind": "text",
34385
+ "optional": false,
34386
+ "meaning": "The ui profile that names the root template."
34387
+ },
34388
+ {
34389
+ "name": "template",
34390
+ "kind": "text",
34391
+ "optional": false,
34392
+ "meaning": "The template that cannot be the application\u0027s shell."
34393
+ },
34394
+ {
34395
+ "name": "blueprint",
34396
+ "kind": "text",
34397
+ "optional": true,
34398
+ "meaning": "The blueprint the template comes from."
34399
+ }
34400
+ ]
34401
+ },
34402
+ {
34403
+ "code": "PLAY0795",
34404
+ "name": "RootTemplateWithoutContentOutlet",
34405
+ "severity": "error",
34406
+ "severities": [
34407
+ "error"
34408
+ ],
34409
+ "title": "A ui profile\u0027s root template has no outlet for the screens\u0027 content.",
34410
+ "reserved": false,
34411
+ "retired": false,
34412
+ "arguments": [
34413
+ {
34414
+ "name": "profile",
34415
+ "kind": "text",
34416
+ "optional": false,
34417
+ "meaning": "The ui profile that names the root template."
34418
+ },
34419
+ {
34420
+ "name": "template",
34421
+ "kind": "text",
34422
+ "optional": false,
34423
+ "meaning": "The root template that has no content outlet."
34424
+ },
34425
+ {
34426
+ "name": "blueprint",
34427
+ "kind": "text",
34428
+ "optional": true,
34429
+ "meaning": "The blueprint the template comes from."
34430
+ },
34431
+ {
34432
+ "name": "outlet",
34433
+ "kind": "text",
34434
+ "optional": false,
34435
+ "meaning": "The outlet the screens\u0027 content is placed in."
34436
+ }
34437
+ ]
34438
+ },
34439
+ {
34440
+ "code": "PLAY0796",
34441
+ "name": "UnknownShellOption",
34442
+ "severity": "warning",
34443
+ "severities": [
34444
+ "warning"
34445
+ ],
34446
+ "title": "A ui profile sets a shell option the root template does not expose.",
34447
+ "reserved": false,
34448
+ "retired": false,
34449
+ "arguments": [
34450
+ {
34451
+ "name": "profile",
34452
+ "kind": "text",
34453
+ "optional": false,
34454
+ "meaning": "The ui profile that sets the option."
34455
+ },
34456
+ {
34457
+ "name": "template",
34458
+ "kind": "text",
34459
+ "optional": false,
34460
+ "meaning": "The root template that does not expose the option."
34461
+ },
34462
+ {
34463
+ "name": "blueprint",
34464
+ "kind": "text",
34465
+ "optional": true,
34466
+ "meaning": "The blueprint the template comes from."
34467
+ },
34468
+ {
34469
+ "name": "option",
34470
+ "kind": "text",
34471
+ "optional": false,
34472
+ "meaning": "The option name."
34473
+ }
34474
+ ]
34475
+ },
34476
+ {
34477
+ "code": "PLAY0797",
34478
+ "name": "InvalidAppearanceValue",
34479
+ "severity": "error",
34480
+ "severities": [
34481
+ "error"
34482
+ ],
34483
+ "title": "A ui profile appearance block has a color scheme that is not light, dark or system, or an accent that is not a hex colour.",
34484
+ "reserved": false,
34485
+ "retired": false,
34486
+ "arguments": [
34487
+ {
34488
+ "name": "profile",
34489
+ "kind": "text",
34490
+ "optional": false,
34491
+ "meaning": "The ui profile whose appearance is invalid."
34492
+ },
34493
+ {
34494
+ "name": "value",
34495
+ "kind": "text",
34496
+ "optional": false,
34497
+ "meaning": "The color scheme or accent as authored."
34498
+ }
34499
+ ]
34500
+ },
34241
34501
  {
34242
34502
  "code": "PLAY0798",
34243
34503
  "name": "DuplicateProfileRootTemplate",
@@ -34248,6 +34508,37 @@
34248
34508
  "title": "A ui profile declares more than one root template.",
34249
34509
  "reserved": false,
34250
34510
  "retired": false
34511
+ },
34512
+ {
34513
+ "code": "PLAY0799",
34514
+ "name": "NewScreenTemplateNotApplicable",
34515
+ "severity": "error",
34516
+ "severities": [
34517
+ "error"
34518
+ ],
34519
+ "title": "A ui profile\u0027s new screens use template default names a template that cannot start a screen in a feature.",
34520
+ "reserved": false,
34521
+ "retired": false,
34522
+ "arguments": [
34523
+ {
34524
+ "name": "profile",
34525
+ "kind": "text",
34526
+ "optional": false,
34527
+ "meaning": "The ui profile that names the template."
34528
+ },
34529
+ {
34530
+ "name": "template",
34531
+ "kind": "text",
34532
+ "optional": false,
34533
+ "meaning": "The template that cannot start a screen in a feature."
34534
+ },
34535
+ {
34536
+ "name": "blueprint",
34537
+ "kind": "text",
34538
+ "optional": true,
34539
+ "meaning": "The blueprint the template comes from."
34540
+ }
34541
+ ]
34251
34542
  }
34252
34543
  ],
34253
34544
  "mcpTools": [
@@ -40019,6 +40310,23 @@
40019
40310
  "additionalProperties": false
40020
40311
  }
40021
40312
  },
40313
+ {
40314
+ "name": "ui-profiles",
40315
+ "requiredParameters": [],
40316
+ "optionalParameters": [
40317
+ "name"
40318
+ ],
40319
+ "inputSchema": {
40320
+ "type": "object",
40321
+ "properties": {
40322
+ "name": {
40323
+ "type": "string"
40324
+ }
40325
+ },
40326
+ "required": [],
40327
+ "additionalProperties": false
40328
+ }
40329
+ },
40022
40330
  {
40023
40331
  "name": "visualize-model",
40024
40332
  "requiredParameters": [],
@@ -42,7 +42,7 @@ Compiler syntax: `cheat-sheet.md`. Negative capability claims depend on the tool
42
42
  35. `description`/`documentation` are authoring metadata: board, MCP and Prologue show them; `cratis render` emits them only as XML doc comments (invalid XML characters are CLI-RENDER-005), never as behavior. A rule only in prose is unenforced in rendered code; make it a rule layer, a spec or a recorded target requirement.
43
43
  36. One unadmitted construct (operations, `numbers exact`, composite view keys) blocks whole-model binding. Routing is admitted (v8), unlike composite view keys. Overrides replace the whole route, filters never match unrouted facts. Do not remove routing or authorization to render a model.
44
44
  37. Personas remain outside ESM bytes, but specifications accept `given caller as <Persona>`: one authenticated deterministic policy witness, not every matching caller. Inspect the chosen `or` branch; use explicit callers when synthesis is refused.
45
- 38. A stored-state rule uses `reads <View>` and `require` with an indented message. Opt into `command reads protected` for eligible v25 views; absence rejects and matching decide/commit changes conflict. Legacy reads remain unprotected. Stage refuses protected reads (STAGE-ESM-044), not the v25 pair: hand-written Arc `[ProtectedDecision]` + `DecisionRead<T>` or Chronicle consistency enforcement needs separate target verification; use a constraint for uniqueness. Forbidden: caller-supplied copies of state in `require`, boolean attestation inputs (`confirmsX == true`), rules hidden in `handler`/implementation-hint prose. An unguarded materialized read is unsafe for a protected decision.
45
+ 38. A stored-state rule uses `reads <View>` and `require` with an indented message. Opt into `command reads protected` for eligible v25 views; absence rejects and matching decide/commit changes conflict. Legacy reads remain unprotected. The Cratis C# renderer refuses protected reads (STAGE-ESM-044), not the v25 pair; semantic Host/executor support is separate: hand-written Arc `[ProtectedDecision]` + `DecisionRead<T>` or Chronicle consistency enforcement needs separate target verification; use a constraint for uniqueness. Forbidden: caller-supplied copies of state in `require`, boolean attestation inputs (`confirmsX == true`), rules hidden in `handler`/implementation-hint prose. An unguarded materialized read is unsafe for a protected decision.
46
46
  Requires Arc 22.39.0 or later for `[ProtectedDecision]`.
47
47
 
48
48
  Identity and compliance traps (`identity.md`, `concepts.md`, `events.md`, `purposes.md`, `diagnostics.md` in the Screenplay documentation):
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: cratis-screenplay-ui-composition
3
- description: Compose the user interface of a Cratis Screenplay `.play` model — `layout` and responsive `arrangement`, screen/dialog templates, component data-context bindings, exposed template configuration, command forms and columns, navigation contributions, application navigation regions (topbar/sidebar, module inherit/extend/override), toolbar slice buttons, blueprint template references, sample data packs, hierarchical outlets/routes, toolbar dialogs, package/icon selection, interaction `behavior`/`on`/`uses` wiring, `ui profile`, `theme`, localized `$strings`, and `file` references. Use when declaring the application shell, reusable screen shapes, component/package configuration, command forms, navigation/toolbars, click or submit behavior, or theming. Do not use for a screen's own data and actions.
3
+ description: Compose the user interface of a Cratis Screenplay `.play` model — `layout` and responsive `arrangement`, screen/dialog templates, component data-context bindings, exposed template configuration, command forms and columns, navigation contributions, application navigation regions (topbar/sidebar, module inherit/extend/override), toolbar slice buttons, blueprint template references, sample data packs, hierarchical outlets/routes, toolbar dialogs, package/icon selection, interaction `behavior`/`on`/`uses` wiring, `ui profile` (root template, shell options, appearance, new screens default), `theme`, localized `$strings`, and `file` references. Use when declaring the application shell, reusable screen shapes, component/package configuration, command forms, navigation/toolbars, click or submit behavior, or theming. Do not use for a screen's own data and actions.
4
4
  license: MIT
5
5
  ---
6
6
 
@@ -81,7 +81,7 @@ Read `references/worked-flow.md` when a complete example is needed before compos
81
81
 
82
82
  ## `layout` — the application shell
83
83
 
84
- One per application, declared at the top level and selected by a `ui profile`.
84
+ One or more per application, declared at the top level; a `ui profile` selects the shell with `root template <Name>`.
85
85
  A complete example:
86
86
 
87
87
  ```screenplay
@@ -267,7 +267,7 @@ precedence, PLAY0485 and examples.
267
267
 
268
268
  ## `ui profile` and `theme`
269
269
 
270
- A `ui profile` selects the layout, theme and `packages`, listed in override-priority order (a later package shadows an earlier one); `target platform` and `target size` accept any identifier, so a typo is silent. Read [references/ui-profile-and-theme.md](references/ui-profile-and-theme.md) when writing a profile or theme.
270
+ A `ui profile` selects the application shell with `root template` (an own layout or application-scope screen template, or `blueprint <B> <Name>` with an optional `version` pin), its shell `option` lines, an `appearance` block (`color scheme`, `accent`), the template new screens start from (`new screens use template`), the theme and the `packages`, listed in override-priority order (a later package shadows an earlier one); `target platform` and `target size` accept any identifier, so a typo is silent. The legacy `layout <Name>` line inside a profile still reads but warns `PLAY0791`: write `root template`. `PLAY0790` to `PLAY0799` check the shell. Read [references/ui-profile-and-theme.md](references/ui-profile-and-theme.md) when writing a profile or theme, or fixing a shell diagnostic.
271
271
 
272
272
  ## Localized strings
273
273
 
@@ -288,6 +288,7 @@ Localized text lives in companion `.strings` files and is referenced unquoted as
288
288
  - [ ] Every slot a `contribute` targets is declared `contributes <Point>` somewhere
289
289
  that encloses it.
290
290
  - [ ] No `dialog template` declares `fits slot`.
291
+ - [ ] Each `ui profile` names its shell with `root template`, not the legacy `layout` line (`PLAY0791`); a blueprint shell is listed under `packages` and its `version` pin is deliberate.
291
292
  - [ ] `packages` are ordered deliberately — later shadows earlier.
292
293
  - [ ] Every theme a profile selects is `compatible with` one of its packages.
293
294
  - [ ] `target platform` and `target size` values are spelled correctly; nothing
@@ -41,7 +41,7 @@ layout AppShell
41
41
 
42
42
  ui profile Desktop
43
43
  target platform web
44
- layout AppShell
44
+ root template AppShell
45
45
 
46
46
  packages
47
47
  core
@@ -200,7 +200,7 @@ field.
200
200
  ```screenplay excerpt
201
201
  ui profile Desktop
202
202
  target platform web
203
- layout AppShell
203
+ root template AppShell
204
204
  packages
205
205
  Product.DesignSystem
206
206
  Cratis.Components
@@ -1,6 +1,124 @@
1
1
  # UI profile and theme
2
2
 
3
- This reference holds the `ui profile` and `theme` excerpt and its rules for platforms, sizes, package order and theme compatibility.
3
+ ## Contents
4
+
5
+ - The shell: `root template`
6
+ - `ui profile` and `theme`
7
+ - Reading and editing the shell
8
+
9
+ This reference holds the `ui profile` and `theme` excerpts and their rules: the root template that names the application shell, shell options, appearance, the new screens default, platforms, sizes, package order and theme compatibility. Requires Screenplay 4.200.0 or later (`screenplay --version`) for the diagnostics `PLAY0790` to `PLAY0799`; 4.197.0 reads the syntax.
10
+
11
+ ## The shell: `root template`
12
+
13
+ A `ui profile` names the template the whole application is drawn in with `root template`. Every screen's template chain is placed in the
14
+ shell's primary outlet (`content`). The reference is the one a `template` assignment uses: an own `layout` or application-scope
15
+ screen template by name, or a template a blueprint ships, `blueprint <Blueprint> <Name>`, with an optional `version "<range>"` pin.
16
+ `ui profile` is the only place that selects the shell; a screen never names it.
17
+
18
+ ```screenplay
19
+ layout AppShell
20
+ category application
21
+ topbar
22
+ side
23
+ content
24
+
25
+ exposure for AppShell
26
+ property topbar.showFooter label "Footer"
27
+
28
+ module Workspaces
29
+ screen template Sheet
30
+ category Page
31
+ scopes feature
32
+ content
33
+
34
+ ui profile Desktop
35
+ target platform web
36
+ target size regular
37
+ theme Nordic
38
+
39
+ root template AppShell
40
+ option showFooter true
41
+
42
+ appearance
43
+ color scheme dark
44
+ accent "#4F46E5"
45
+
46
+ new screens use template Sheet
47
+
48
+ packages
49
+ Cratis.Components
50
+
51
+ theme Nordic
52
+ compatible with Cratis.Components
53
+ ```
54
+
55
+ A shell from a blueprint lists the blueprint under `packages` (the blueprint's name is a package) and may pin a version:
56
+
57
+ ```screenplay
58
+ ui profile Web
59
+ packages
60
+ Cratis.Blueprint.Default
61
+
62
+ root template blueprint Cratis.Blueprint.Default AppShell version "^4.5"
63
+ new screens use template blueprint Cratis.Blueprint.Default Detail
64
+ ```
65
+
66
+ - `root template`: at most one per profile. The shell is a `layout`, or a screen template that declares `scopes application` and fits no slot. It
67
+ needs a `content` slot, or no screen has a place in it.
68
+ - `option <name> <value>`: a configurable item the shell exposes (an own shell exposes the properties of its `exposure for <Shell>`).
69
+ The value is a bare word, a quoted string, a number, `true` or `false`. Set each name once.
70
+ - `appearance`: `color scheme` is `light`, `dark` or `system`; `accent` is a quoted `#RGB`, `#RRGGBB` or `#RRGGBBAA`. One block per profile.
71
+ - `new screens use template`: the template a new screen starts from in a designer. It is an authoring default, it changes no existing
72
+ screen, and it has to be able to start a screen in a feature (not a layout or an application-scope root; a `scopes` list that leaves
73
+ out `feature` is refused).
74
+ - A version range only applies to a blueprint template; `*`, an exact version or a `^`, `~`, `>=`, `>`, `<=` or `<` range.
75
+
76
+ ### Errors and fixes
77
+
78
+ | Code | Severity | Cause | Fix |
79
+ | --- | --- | --- | --- |
80
+ | `PLAY0788` | Error | A `root template` or `new screens use template` line is malformed, or it pins a version on an own template | Write `[blueprint <B>] <Name> [version "<range>"]`; drop the version on an own template |
81
+ | `PLAY0789` | Error | A malformed `appearance` line, a repeated line, or two `appearance` blocks | `color scheme <word>` / `accent "<colour>"`, each once, one block |
82
+ | `PLAY0790` | Error | The template is not declared in the document (or the blueprint does not ship it) | Declare `layout <Name>` or `screen template <Name>`, or take it from a blueprint |
83
+ | `PLAY0791` | Warning | The profile still selects its shell with the legacy `layout <Name>` line | Write `root template <Name>`; remove the `layout` line when a `root template` is present (the quick fix does either) |
84
+ | `PLAY0792` | Error | The blueprint is not listed in the profile's `packages` (or not installed) | Add it under `packages` |
85
+ | `PLAY0793` | Warning | The pinned `version` range is not satisfied by the installed blueprint | Move the pin or update the blueprint |
86
+ | `PLAY0794` | Error | The root template cannot be the shell: a dialog or ordinary screen template, a slot-fitting template, `scopes` without `application` | Choose a layout or an application-scope template |
87
+ | `PLAY0795` | Error | The root template has no `content` slot | Add the line `content` to it |
88
+ | `PLAY0796` | Warning | An `option` the shell does not expose | Use a name the shell exposes, or add the property to its `exposure` |
89
+ | `PLAY0797` | Error | An invalid color scheme or accent | `light`, `dark` or `system`; a quoted hex colour |
90
+ | `PLAY0798` | Error | More than one `root template` in one profile | Keep one |
91
+ | `PLAY0799` | Error | The `new screens use template` default cannot start a screen in a feature | Name a feature-scope screen template |
92
+
93
+ What a blueprint ships is only known where the blueprint is installed, so its checks (`PLAY0790` for a template it lacks, `PLAY0793`,
94
+ the options and outlets of its templates) come from the host that has the catalog (Stage, the `cratis` CLI, the MCP server); the compiler
95
+ decides everything the document alone decides.
96
+
97
+ ### Negative example: the legacy `layout` line
98
+
99
+ `layout <Name>` inside a profile still reads, but it is the old way to name the shell. Do not write it in a new model:
100
+
101
+ ```screenplay excerpt
102
+ layout AppShell
103
+ category application
104
+ topbar
105
+ content
106
+
107
+ ui profile Desktop
108
+ layout AppShell
109
+ ```
110
+
111
+ The canonical form is `root template AppShell`:
112
+
113
+ ```screenplay
114
+ layout AppShell
115
+ category application
116
+ topbar
117
+ content
118
+
119
+ ui profile Desktop
120
+ root template AppShell
121
+ ```
4
122
 
5
123
  ## `ui profile` and `theme`
6
124
 
@@ -10,7 +128,7 @@ Excerpt: `AppShell` is the layout above.
10
128
  ui profile Desktop
11
129
  target platform web
12
130
  target size regular
13
- layout AppShell
131
+ root template AppShell
14
132
  theme Nordic
15
133
  packages
16
134
  Cratis.Components
@@ -32,3 +150,7 @@ theme Nordic
32
150
  - `compatible with` lists the packages a theme actually supports, each at most
33
151
  once. A profile selecting a theme not declared compatible with one of its own
34
152
  packages gets a compile-time **warning**.
153
+
154
+ ## Reading and editing the shell
155
+
156
+ `ui-profiles` (MCP, Screenplay 4.201.0 or later) returns every profile's root template, options, appearance and new screens default with the shell diagnostics, and the own templates that could be the root template or the new screens default. Edit with `propose-ast` on `RootTemplateSyntax`, `ShellOptionSyntax` (`syntaxKind` is the value's kind), `ProfileAppearanceSyntax` and `NewScreenTemplateSyntax`; an invalid reference is refused with its code.
@@ -146,6 +146,31 @@
146
146
  "kind": "skill-contains",
147
147
  "value": "references/application-shell.md"
148
148
  },
149
+ {
150
+ "kind": "skill-contains",
151
+ "value": "`ui profile` is the only place that selects the shell",
152
+ "file": "references/ui-profile-and-theme.md"
153
+ },
154
+ {
155
+ "kind": "skill-contains",
156
+ "value": "| `PLAY0791` | Warning |",
157
+ "file": "references/ui-profile-and-theme.md"
158
+ },
159
+ {
160
+ "kind": "skill-contains",
161
+ "value": "| `PLAY0799` | Error |",
162
+ "file": "references/ui-profile-and-theme.md"
163
+ },
164
+ {
165
+ "kind": "skill-contains",
166
+ "value": "`layout <Name>` inside a profile still reads",
167
+ "file": "references/ui-profile-and-theme.md"
168
+ },
169
+ {
170
+ "kind": "skill-contains",
171
+ "value": "`root template` (an own layout or application-scope screen template",
172
+ "file": "SKILL.md"
173
+ },
149
174
  {
150
175
  "kind": "skill-contains",
151
176
  "value": "A module's own items may only target that module",