@cratis/pi 2.23.1 → 2.24.1

package/package/corpus/skills/cratis-screenplay-specifications/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: cratis-screenplay-specifications
+description: Pin behavior in a Cratis Screenplay `.play` model with given/when/then `specification` blocks — prior events and read-model state, the command under test, expected events, read-model state, query results and rejections, plus what the reference execution actually runs. Use when writing acceptance criteria for a slice, specifying a rejection, or deciding whether a rule belongs in a specification or in the type system. Do not use for C# or TypeScript test code.
+license: MIT
+---
+
+# Screenplay specifications
+
+A `specification` is the acceptance criterion for a slice, written in the same
+document as the behavior it pins. Given/when/then, in business language, with
+concrete data.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | Parser, semantic binder, reference execution |
+
+Read from the Screenplay repository at tag `v4.12.1` (commit `122eee8`), against
+`Documentation/screenplay/specifications.md` and
+`Source/DotNET/Screenplay/Parsing/SpecificationParser.cs`. Reverify before
+claiming another version behaves the same.
+
+## The vocabulary
+
+| Construct | Meaning |
+| --- | --- |
+| `given <EventType>` | prior state, established by replaying events before the command runs |
+| `given readmodel <ReadModelType>` | prior read-model state, established directly |
+| `when <CommandType>` | the command under test — **at most one**; a second is a compile error |
+| `then <EventType>` | an event expected to be produced |
+| `then readmodel <ReadModelType>` | the read-model state expected afterwards |
+| `then query <Query>` | ordered query results for explicit arguments |
+| `arguments` | the values supplied to the query |
+| `result` | one expected query result; repeat for many |
+| `then error "<message>"` | a rejection, for the named reason |
+| `then error` | a rejection, for a reason this specification does not name |
+| `<property> = <value>` | a property value, using the `produces` expression grammar |
+
+`given`, `then`, `then readmodel`, `then query` and `then error` are each zero or
+more.
+
+## Command specifications
+
+```screenplay
+specification RegisteringADraftInvoice
+  given CustomerRegistered
+    customerId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+    name       = "Acme Corp"
+  when RegisterInvoice
+    invoiceId     = "9c858901-8a57-4791-81fe-4c455b099bc9"
+    customerId    = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+    invoiceNumber = "INV-000123"
+  then InvoiceRegistered
+    invoiceId     = "9c858901-8a57-4791-81fe-4c455b099bc9"
+    invoiceNumber = "INV-000123"
+```
+
+**`then` contains either events or an error — never both.**
+
+## Rejections — two forms, and they say different things
+
+```screenplay
+specification RejectingAnInvoiceWithNoLines
+  when RegisterInvoice
+    invoiceId = "9c858901-8a57-4791-81fe-4c455b099bc9"
+  then error "An invoice must have at least one line"
+```
+
+`then error "<message>"` says **rejected, for this reason** — pinning a constraint
+violation or a validation message down deliberately.
+
+```screenplay
+specification RejectingAnInvoiceWhoseNumberIsAlreadyTaken
+  given InvoiceRegistered
+    invoiceNumber = "INV-000123"
+  when RegisterInvoice
+    invoiceNumber = "INV-000123"
+  then error
+```
+
+Bare `then error` says **rejected, for a reason this specification does not name**.
+Most specifications are this kind — the reason lives in the specification's name.
+
+## View specifications
+
+```screenplay
+specification SendingADraftInvoice
+  given readmodel InvoiceListReadModel
+    invoiceId = "9c858901-8a57-4791-81fe-4c455b099bc9"
+    status    = "draft"
+  when ChangeInvoiceStatus
+    status = "sent"
+  then readmodel InvoiceListReadModel
+    status = "sent"
+```
+
+**Views cannot reject events.** There are no error cases for a projection.
+
+## Query specifications
+
+```screenplay
+specification LookingUpARegisteredProject
+  when RegisterProject
+    projectId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+    name      = "Screenplay"
+  then query ProjectById
+    arguments
+      projectId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+    result
+      projectId = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+      name      = "Screenplay"
+```
+
+Results are compared **in order**. `then query` with no `result` block asserts the
+query returns nothing.
+
+## Business rule or type system?
+
+Before writing an error specification, apply this test:
+
+1. Does the error depend on **existing system state** — what events occurred?
+   → business rule → write the specification.
+2. Can the type system make the invalid state unrepresentable?
+   → in Screenplay that means a `concept` with its own `validate` block, and the
+   rule travels with every use → **not** a specification.
+3. Would a different business plausibly have a different rule here?
+   → business rule → specification.
+
+**Write specifications for:** *"Cannot cancel an already-paid invoice"*,
+*"Cannot withdraw more than the balance"*, *"Maximum 100 lines per invoice"*.
+
+**Do not write specifications for:** *"Invoice number must match INV-000000"*,
+*"Name cannot be empty"*, *"Discount must be between 0 and 100"* — those belong on
+the concept.
+
+## Application-boundary coverage
+
+Every slice should carry at least one specification whose `when` is the command a
+real caller issues and whose `then` is observable at that same boundary — produced
+events, read-model state, or query results. A specification satisfiable only by an
+internal function describes a unit, not a slice acceptance criterion.
+
+## Reference execution — what actually runs
+
+Screenplay supplies a framework-neutral reference path: no Arc, no Chronicle, no
+database, no filesystem, no network. It executes against an immutable in-memory
+world so every downstream target has one normalized behavior to match.
+
+> The minimum evaluator currently admits the RegisterProject-style vertical:
+> `not empty` validation, unconditional event production, one affected read-model
+> instance, optional snapshot lookup, and exact ordered specification results.
+> Unsupported reachable capabilities **block plan creation** rather than producing
+> a partial or stubbed execution.
+
+A rejected execution returns the unchanged world. An accepted one commits its
+facts and projected state once, then evaluates the requested queries against that
+state.
+
+⚠️ **`for <event-source-value>` is reserved for ESM v2.** The parser, printer and
+syntax tree preserve it, but ESM v1 binding reports blocking diagnostic
+`PLAY0268`. It cannot execute or render silently. Avoid it in a model that must
+run today.
+
+## Quality checklist
+
+For every specification:
+
+- [ ] Concrete, realistic values — never "valid user" or "some amount".
+- [ ] Tests exactly one behavior, independent of other specifications.
+- [ ] Business language matching the event-model vocabulary.
+
+For command specifications:
+
+- [ ] `given` contains only events, each with all its fields.
+- [ ] `when` contains exactly one command with all its inputs.
+- [ ] `then` contains **either** events **or** an error, never both.
+- [ ] Error cases test business rules, not format validation.
+
+For view specifications:
+
+- [ ] `given readmodel` is the complete state before.
+- [ ] `then readmodel` is the complete state after.
+- [ ] No error cases — views cannot reject.
+
+## Verify
+
+- [ ] `screenplay <model> --warnaserror` reports zero errors and zero warnings.
+- [ ] Every slice has at least one boundary specification.
+- [ ] The rejections are specified, not only the happy path.
+- [ ] No `given`/`when`/`then` clause names an element the model does not declare.
+- [ ] No `for <event-source-value>` in a model that must reach a runtime.
+
+## Route near misses
+
+- The rules being specified: `cratis-screenplay-command-surface`.
+- The projections being asserted on: `cratis-screenplay-projections`.
+- Naming and scoping specifications generally: `cratis-specification-by-example`.
+- C# specifications for hand-written Cratis code: `cratis-specifications-csharp`.

package/package/corpus/skills/cratis-screenplay-specifications/verification.json

@@ -0,0 +1,19 @@
+{
+  "skill": "cratis-screenplay-specifications",
+  "input": "Write given/when/then specifications for a Screenplay slice.",
+  "fixtures": [],
+  "assertions": [
+    {
+      "kind": "skill-contains",
+      "value": "**`then` contains either events or an error \u2014 never both.**"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "Views cannot reject events"
+    },
+    {
+      "kind": "skill-contains",
+      "value": "PLAY0268"
+    }
+  ]
+}

package/package/corpus/skills/cratis-screenplay-ui-composition/LICENSE

@@ -0,0 +1,2 @@
+Copyright (c) Cratis. All rights reserved.
+Licensed under the MIT license. See LICENSE file in the project root for full license information.

package/package/corpus/skills/cratis-screenplay-ui-composition/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: cratis-screenplay-ui-composition
+description: Compose the user interface of a Cratis Screenplay `.play` model — `layout` and its responsive `arrangement`, `screen template` and `dialog template`, command-bound `form` declarations, navigation `contribute` blocks, `ui profile`, `theme`, localized `$strings`, and `file` realization references. Use when declaring the application shell, a reusable screen shape, a command form, a navigation entry, or theming in a `.play` model. Do not use for a screen's own data and actions.
+license: MIT
+---
+
+# UI composition in Screenplay
+
+Event Modeling's wireframe step is a first-class part of the language. The shell,
+the reusable shapes inside it, the forms bound to commands, and the navigation
+entries other modules contribute are all declared in the `.play` model.
+
+## Verified product sources
+
+| Package | Version | Purpose |
+| --- | --- | --- |
+| `Cratis.Screenplay` | `4.12.1` | Layout, template, form, contribution, profile and theme parsers |
+
+Read from the Screenplay repository at tag `v4.12.1` (commit `122eee8`), against
+`Documentation/screenplay/{templates,layout-arrangement,forms,contributions,ui-profile,theme,internationalization,file-references}.md`
+and `Source/DotNET/Screenplay/Parsing/`. Reverify before claiming another version
+behaves the same.
+
+These constructs went unhighlighted and uncompleted by the Monaco and VS Code
+language service until `Cratis/Screenplay#199` gave every construct the parser
+dispatches on a keyword entry. On an older language-service version they still
+look unrecognized — **check `screenplay`, not the editor**, because absent
+highlighting was never evidence that a construct is wrong.
+
+## `layout` — the application shell
+
+One per application, declared at the top level and selected by a `ui profile`.
+
+```screenplay
+layout AppShell
+  topbar
+  navigation contributes Navigation
+  content
+  footer
+
+  arrangement flow
+    column
+      topbar height 56
+      row
+        navigation width 240
+        content grow
+      footer height 32
+```
+
+A slot is declared once by name, optionally marked
+`contributes <ContributionPoint>` to make it a contribution target.
+
+## `arrangement` — responsive `flow` or pixel-precise `freeform`
+
+The size-class matrix is **2×2**: width `compact` or `regular`, height `compact`
+or `regular` — phone landscape, phone portrait, desktop short, desktop tall.
+
+**`arrangement flow`** nests slots under `row`, `column` or `grid` containers.
+
+- A container may declare `gap <n>`.
+- A slot leaf takes `width <n>`, `height <n>`, `grow`, and `span <n>` for grid tracks.
+- `when width <class>[, height <class>]` or `when height <class>` **replaces the
+  entire tree** for that condition — it is not a partial override.
+
+**`arrangement freeform`** declares one variant per matrix point:
+
+```screenplay
+arrangement freeform
+  variant width regular, height regular
+    place navigation at 0,0 size 240,fill
+    place content    at 240,0 size fill,fill
+  variant width compact, height regular
+    place navigation hidden
+    place content    at 0,0 size fill,fill
+```
+
+`place <Slot> at <x>,<y> size <w>,<h>` where either dimension may be `fill`, or
+`place <Slot> hidden` to drop the slot from that variant entirely.
+
+## `screen template` and `dialog template`
+
+Declared at module level, referenced by screens.
+
+```screenplay
+screen template MasterDetail
+  fits slot content
+  sidebar
+  main
+  arrangement flow
+    row gap 16
+      sidebar width 280
+      main grow
+
+dialog template RegisterInvoiceDialog
+  body
+  actions
+```
+
+`fits slot <name>` says which slot of its parent the template fills. **A dialog
+template is a screen template in everything but one respect: it declares no
+`fits slot`, because a dialog occupies no slot of the structure it opens over** —
+writing one is an error.
+
+A screen fills a template by naming it and providing slot bodies; a dialog is
+filled exactly the same way, because from the screen's side there is no
+difference. See `cratis-screenplay-read-surface` for the directives that go inside.
+
+## `form` — bound to a command
+
+```screenplay
+form RegisterInvoiceForm for RegisterInvoice
+  populate via query GetInvoiceDefaults by customerId
+  field invoiceNumber label "Invoice #"
+  field customerId    from item
+  field total         compose using TotalCalculator
+  on submit navigate to InvoiceList
+```
+
+- At most one `populate` — `populate via query <Query> [by <param>]` or
+  `populate from item`.
+- `field <property>` takes at most one of `from <source>` or `compose using
+  <Callback>`, plus an optional `label`.
+- At most one `on submit navigate to <Screen> [by <param>]`.
+
+⚠️ **A form is discovered, not referenced.** It never appears in a screen's
+directive tree the way a `table` or `summary` does — it is found by its
+`for <Command>` binding wherever that command is invoked. A form sits at module
+level, so it disambiguates by module rather than by feature or slice.
+
+## `contribute` — navigation from elsewhere
+
+```screenplay
+contribute to Navigation
+  navigate to InvoiceList
+  label "Invoices"
+  order 20
+```
+
+All three directives are optional and appear at most once each.
+
+**Resolution walks outward:** a contribution first looks for a
+`contributes <ContributionPoint>` slot among its **own module's** templates, then
+outward to the nearest enclosing structure that declares a matching point. Three
+tiers exist — application-wide (the layout declares the point), cross-module, and
+module-level.
+
+`navigate to <Screen> by <param>` is **not** string interpolation; it reuses the
+same typed navigate binding a screen action uses.
+
+⚠️ This iteration ships `navigate`, `label` and `order` only. Grouping beyond a
+flat ordered list, and an explicit override for when nearest-enclosing is not the
+point you mean, are deliberately left for later.
+
+## `ui profile` and `theme`
+
+```screenplay
+ui profile Desktop
+  target platform web
+  target size regular
+  layout AppShell
+  theme Nordic
+  packages
+    Cratis.Components
+
+theme Nordic
+  compatible with Cratis.Components
+```
+
+- `target platform` takes a comma-separated list. `web`, `ios` and `android` are
+  the documented examples; ⚠️ **the parser accepts any identifier** — there is no
+  enforced list, so a typo is silent.
+- `target size` is documented as `compact`, `regular` or `expanded`; ⚠️ again any
+  identifier parses.
+- `packages` are listed **in override-priority order** — a later package's `Button`
+  shadows an earlier one's — and `core`, the built-in vocabulary, is always the
+  final fallback.
+- `compatible with` lists the packages a theme actually supports, each at most
+  once. A profile selecting a theme not declared compatible with one of its own
+  packages gets a compile-time **warning**.
+
+## Localized strings
+
+Localized text lives in companion `.strings` files — `MySystem.play` pairs with
+`MySystem.<locale>.strings`, line-based, dotted keys, `=` assignment, `//`
+comments. `{placeholder}` tokens are kept verbatim for runtime substitution.
+
+Reference them with `$strings.<dotted.key>`, unquoted, anywhere a literal is
+accepted in: a validation rule's `message`; a screen action, table column or
+summary field `label`; a screen or section `title`; a contribution `label`; and a
+form field `label`. The value is stored as the literal text `$strings.<key>`, and
+the printer emits it unquoted so a round trip preserves it.
+
+## `file` — realization metadata, never a substitute
+
+Two meanings, one word. On a construct **with an implementation body** — a command
+`handler`, a validation rule predicate, a query `performer`, a reducer rule, a
+reaction trigger, a `constraint` and a `screen` — `file` stands in for the inline
+body. It sits on the **screen itself**, not on a directive inside it: `File` is a
+member of `ScreenSyntax`, and the directive types have no such member. On a **pure declaration** — `concept`, `type`, `event`, `readmodel`,
+`projection`, `slice`, `specification`, top-level `trigger` — it only records
+which file realizes it.
+
+The rules: **repository relative, never absolute** (an absolute path is warning
+`PLAY0264`); **never resolved** — the compiler does not look for the file, so a
+stale path does not invalidate the document; and **never replaces the
+declaration** — a `projection` still declares its blocks, an `event` still declares
+its properties.
+
+⚠️ `file <Identifier>` is read as a **property** named `file`, not a directive —
+the type-reference shape wins the tie. `file Invoices/Register.cs` is a directive;
+`file Attachment` is a property. In a `trigger` body the directive always wins, so
+a trigger value named `file` is written `@file`.
+
+## Verify
+
+- [ ] `screenplay <model> --warnaserror` reports zero errors and zero warnings.
+- [ ] Every slot a `contribute` targets is declared `contributes <Point>` somewhere
+      that encloses it.
+- [ ] No `dialog template` declares `fits slot`.
+- [ ] `packages` are ordered deliberately — later shadows earlier.
+- [ ] Every theme a profile selects is `compatible with` one of its packages.
+- [ ] `target platform` and `target size` values are spelled correctly; nothing
+      checks them.
+- [ ] User-visible text is `$strings.` where the application is localized.
+- [ ] No `file` reference is doing work the declaration should be doing.
+
+## Route near misses
+
+- A screen's own data, actions and name resolution: `cratis-screenplay-read-surface`.
+- Deriving wireframes from the model (step 4): `cratis-screenplay-event-modeling`.
+- Building the actual React application: `cratis-arc-react-page`, `cratis-components-styling`.

package/package/corpus/skills/cratis-screenplay-ui-composition/verification.json

@@ -0,0 +1,10 @@
+{
+  "skill": "cratis-screenplay-ui-composition",
+  "input": "Declare the application shell, a screen template and a command form.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "A form is discovered, not referenced" },
+    { "kind": "skill-contains", "value": "declares no\n`fits slot`" },
+    { "kind": "skill-contains", "value": "override-priority order" }
+  ]
+}

package/package/corpus/skills/cratis-stage-rendering-and-sandbox/SKILL.md

@@ -234,8 +234,11 @@ runtime. A green `results.json` is not a passing integration test.
 
 ## Route near misses
 
-- Writing or verifying the `.play` model itself:
-  `cratis-screenplay-model-authoring`.
+- Writing or verifying the `.play` model itself: `cratis-screenplay-model-authoring`
+  for the compiler and the admitted set, `cratis-screenplay-event-modeling` for the
+  modeling method, and the per-surface `cratis-screenplay-*` skills for the
+  constructs — command surface, projections, read surface, UI composition,
+  captures and reactions, specifications.
 - Understanding the generated Arc command, validator or read model as C#:
   `cratis-arc-command` and the Chronicle read-model guidance.
 - Inspecting the Chronicle store the sandbox writes into: the Chronicle CLI or

package/package/profile-catalog.json

@@ -676,7 +676,14 @@
     {
       "id": "cratis/screenplay",
       "availableTargets": [
-        "cratis-screenplay-model-authoring"
+        "cratis-screenplay-captures-and-reactions",
+        "cratis-screenplay-command-surface",
+        "cratis-screenplay-event-modeling",
+        "cratis-screenplay-model-authoring",
+        "cratis-screenplay-projections",
+        "cratis-screenplay-read-surface",
+        "cratis-screenplay-specifications",
+        "cratis-screenplay-ui-composition"
       ],
       "languages": [
         "language-agnostic"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "2.23.1",
+  "version": "2.24.1",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [