---
title: UI contract
editUrl: https://github.com/Cratis/Screenplay/edit/main/Documentation/screenplay/ui-contract.md
description: Export every screen of a Screenplay model as a stack-neutral JSON contract of its data, actions, navigation and layout, so any UI stack can build from it.
lastUpdated: 2026-11-15T00:00:00.000Z
---


## Build a UI on any stack from the model

[Screens](/screenplay/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:

```bash
screenplay export path/to/screenplays --format ui --output screens.json
```

Over 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](/screenplay/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

```json
{
  "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

`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

A [component an extension provides](/screenplay/screens/#extension-components) is a `scene` component with an `extension` member, and the screen lists the extensions it needs:

```json
{
  "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

`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

```csharp
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

A [free screen](/screenplay/screens/#free-screens-declare-a-screen-first-let-a-slice-adopt-it) 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:

```bash
screenplay export path/to/screenplays --screens --output model.esm.json
```

Over MCP, `read-workspace` with `view: "executable-model"` and `screens: true`
pages the same bytes. From .NET:

```csharp
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](/screenplay/interoperability/#claimed-unreleased-version) 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.
