From a model to a running extension
A model says which systems exist, which abilities they offer and which screens place which components. A locked package says what the extension really is: its components, what each may invoke, the signals it raises, its settings and its backend. Stage joins the two when it starts, and what the extension hosting answers from afterwards is that join, not a list somebody configured.
What comes from where
Section titled “What comes from where”| Stage asks | Answered from | By |
|---|---|---|
| Which abilities can be invoked, with which effect and outcomes | The model’s systems that a loaded package realizes, whose abilities Screenplay binds from the package’s contract | ExtensionModelCatalogs.Abilities |
| Which component a screen places, and what it may invoke and raise | The UI contract of the model (scene.components[].extension) and the package’s contract |
ExtensionModelCatalogs.Placements |
| Which backends a screen needs | The UI contract’s extensions of each screen |
ExtensionModelCatalogs.Usage |
| Which settings a system has, and which a browser may read | The package’s contract. Only public reaches a browser; secret and backend do not |
ExtensionModelCatalogs.Settings |
| Which package an ability, a component or a backend belongs to | The system’s extension reference, matched to the lock entry that pins it |
PinnedAbilityCatalog |
| The element the browser loads for a placed component | The scene Stage builds from the same model, with the package’s frontend, abilities and signals added, and each on <signal> bound to Scene’s signal trigger |
ExtensionSceneComponents |
SemanticHost does this once the packages are loaded and the model has compiled, and it is what turns the empty catalogs the extension hosting
starts with (see Run extension components) into the model’s.
A system that no loaded package realizes has no abilities in the catalog, so an invocation of it is refused rather than started. A component the
package’s contract does not declare is not placed, so asking for it answers 404.
Compiling the model needs the lock. Stage looks for screenplay.lock beside the model, not beside the directory it was started from, and compiles
the model against the contracts of the packages it loaded.
The Notifier sample
Section titled “The Notifier sample”Samples/Extensions/Notifier is a minimal extension with everything the
path needs:
| File | What it is |
|---|---|
contract.play |
The extension’s contract: the Notify ability (once, with a Muted outcome), the NoticeBoard React component that may invoke Notify and raises dismissed, a public channel setting and a secret token. |
frontend/index.js |
The component, built on @cratis/scene.extensions. React and the extensions package come from Stage’s import map. |
placeholders/notice-board.html |
The static placeholder design tools draw instead of the component. |
backend/ |
The backend, written with the C# SDK. |
A model uses it by naming the package on a system and placing the component on a screen:
system Notifier description "Posts notices to a chat channel" extension "ghcr.io/acme/extension-notifier"
screen NoticeBoard title "Notices" component Notifier.NoticeBoard board property title = "Today"The specifications in Source/Host/Extensions/for_ExtensionEndToEnd run that, with a real Orleans silo and the gRPC protocol, over the sample’s
own files:
- Loaded from a lock. The sample is packed, signed and loaded through the package loader from a
screenplay.lockentry, and the model compiles against its contract. - Lazy activation. Nothing is started when Stage starts. Reaching the
NoticeBoardscreen starts theNotifierbackend, once. - Invoked from a screen. The component’s
invokegoes through the browser gateway: the screen must place the component, the contract must allow the ability and the person must be signed in. The invocation is recorded with the screen interaction as its cause and pinned to the locked package. - Answered durably. The backend answers, the invocation settles in the ledger with the outcome and output, and asking again with the same interaction finds that invocation instead of doing the effect twice.
The backend in these specifications is a loopback gRPC server that speaks the same protocol and declares the same ability as the sample’s backend, because the Stage host project and the SDK each generate the protocol types. The sample’s backend is built with the solution, and the conformance suite holds each SDK to the protocol.
In the browser
Section titled “In the browser”When a component is placed, the page asks Stage to start its system’s backend before the component has loaded, with
POST /stage/extensions/activation/screens/<screen>. It carries nothing but the screen and a failure does not stop the component loading: the
first invocation starts the backend anyway. See Execution tiers for what starting means.
Not done yet
Section titled “Not done yet”- Screen authorization. A placement can name the policy of its screen, but the UI contract does not name one yet, so a browser invocation
needs a signed-in person and nothing more. The ability’s own
authorizestill applies. - Setting values from the model. The values behind
setting <name> = ...andsetting <name> from secret ...on a system are not read from the model yet; settings resolve from configuration undersystems:<System>:<setting>. - Strings.
$stringsreferences in a component’s properties are not resolved into the element’sstrings.