UI contract
Build a UI on any stack from the model
Section titled “Build a UI on any stack from the model”Screens are written with Scene vocabulary. A builder for React without Scene, Vue, Angular or a native app needs to know what each screen shows, which commands it issues, where it leads and how it is laid out, without interpreting Scene. The UI contract says exactly that:
screenplay export path/to/screenplays --format ui --output screens.jsonOver MCP, read-workspace with view: "ui-contract" pages the same bytes.
The contract needs only the sources. When the model also has an executable
model, every screen, query and command carries its semantic identity and its
HTTP route from the API description, and modelRevision
names the executable model they come from. Without one, those members are
absent and the CLI says so on standard error.
What a screen holds
Section titled “What a screen holds”{ "name": "BookCatalog", "slice": "Lending.Catalog.BookCatalog", "title": "Catalog", "data": [ { "query": "AllBooks", "readModel": "CatalogEntry", "many": true, "fields": [{ "property": "title", "label": "Title" }], "route": "/api/lending/catalog/book-catalog/all-books", "live": true } ], "actions": [ { "command": "BorrowBook", "label": "BorrowBook", "subject": "item", "inputs": [ { "name": "bookId", "type": "BookId", "from": "item.bookId" }, { "name": "memberId", "type": "MemberId" } ], "route": "/api/lending/catalog/borrow-book" } ], "navigation": [{ "screen": "BookDetails", "trigger": "row", "by": "bookId" }], "layout": { "fits": [], "regions": [{ "kind": "list", "shows": "CatalogEntry", "regions": [], "actions": [] }] }}| Member | Meaning |
|---|---|
data |
One entry per query the screen shows: the read model, whether it is a list, the value it is narrowed by, the fields shown with their labels (empty when the screen shows them all) and whether it is live |
actions |
One entry per command the screen issues: what it applies to (screen or item), its inputs with their types and the screen value that fills each one (from), and, for an action that picks one of several commands, the condition in when |
navigation |
Where the screen leads and what leads there: a link, a table row, an action, a toolbar button or a behavior trigger such as click, with the value passed by and how the target opens |
layout |
Where the screen fits (page, dialog, drawer, pane, panel), the screen shape (template) it follows, and its regions: template, slot, section, list, details, embed, component and toolbar, with the actions placed in each |
Nothing in these members needs Scene to interpret: a component region names
the component instance and nothing else.
The Scene layer
Section titled “The Scene layer”scene is present only when a screen uses Scene vocabulary, and a builder for
another stack may ignore it. It lists the Scene templates with their blueprint
and slots, the components with their properties, bindings and presentation
values, the toolbars and the outlets a screen offers to lower levels. A
component property keeps its binding (query AllBooks) or its value; lists
and objects stay JSON.
Extension components
Section titled “Extension components”A component an extension provides is a scene component with an extension member, and the screen lists the extensions it needs:
{ "extensions": [{ "system": "Payments", "reference": "cratis/stripe" }], "scene": { "components": [{ "component": "Payments.PaymentForm", "name": "payment", "extension": { "system": "Payments", "reference": "cratis/stripe", "component": "PaymentForm", "kind": "react", "platforms": ["web"], "placeholder": "placeholders/payment-form.html", "placeholderHtml": "<p>Pay</p>", "handles": ["succeeded"] } }] }}system and component name the placement; a host resolves it through the system’s extension, never through a package, so swapping a compatible provider changes nothing here. kind, platforms and placeholder come from the restored contract and are left out when it is not restored. placeholderHtml is the static placeholder a design tool draws in place of the component, present only when the restored package holds the file and it has no script or external reference. handles lists the signals the screen handles with on.
A screen’s extensions lists each extension it needs, so a host can start the backend before the first call from the browser. The member is left out of a screen that places no extension component.
Versions and round trips
Section titled “Versions and round trips”contract names the version, screenplay-ui/1. The same model always gives
the same bytes, and reading them back with UiContractJson.Read and writing
again gives the same bytes. A reader refuses another version.
Use it from .NET
Section titled “Use it from .NET”using Cratis.Screenplay.Ui;
var contract = UiContractBuilder.For(workspace);foreach (var screen in contract.Screens){ Console.WriteLine($"{screen.Slice}.{screen.Name}: {screen.Data.Count} data, {screen.Actions.Count} actions");}
File.WriteAllBytes("screens.json", UiContractJson.Write(contract));UiContractBuilder.For(syntax, model, application) reads a merged
ApplicationSyntax with an optional executable model, and
UiContractBuilder.Select(contract, scope) keeps the screens of one module,
feature or slice.
Screens in the executable model
Section titled “Screens in the executable model”A free screen reaches the contract once per slice that
adopts it: the contract screen names the adopting slice and carries the data that slice’s provisions resolve, with the read model
paths mapped back to the screen’s fields. A free screen no slice adopts is design-only and is not part of the contract. In the
executable model such a screen is held by the application, with the needs it leaves to its adopters, and each adopting slice holds
its adoptions; that is ESM v56, selected only when a free screen is admitted. Admission refuses a need no slice provides, with
a reason that names the screen and the shape.
The neutral members of every screen can also live in the executable model itself, as ESM v42. Admission is on request, so a default compilation keeps its version, bytes and revision:
screenplay export path/to/screenplays --screens --output model.esm.jsonOver MCP, read-workspace with view: "executable-model" and screens: true
pages the same bytes. From .NET:
using Cratis.Screenplay.Ui;
var admitted = ExecutableScreens.Admit(workspace);if (!admitted.Success){ foreach (var refusal in admitted.Refusals) Console.Error.WriteLine(refusal); return;}
var model = admitted.Compilation!.Model;var contract = UiContractBuilder.For(model);Each slice then holds its screens: the data a screen shows keyed to query
identities, its actions keyed to command identities with every input as a
command property identity, and its navigation keyed to screen identities, with
the layout regions as written. UiContractBuilder.For(model) reads the
screenplay-ui/1 contract from that model alone, without the sources and
without the Scene layer; its neutral members equal the ones read from the
sources.
A reference the executable model does not hold refuses admission with a reason that names the screen and the reference; nothing is dropped. A model without an executable model has nothing to admit screens to. See the ESM interoperability notes for the exact members.
Behavior wiring beyond navigation and command execution (refreshing a query,
setting state, notifications, dialogs opened from a template) is not in
screenplay-ui/1; read it from the screen’s source.