Skip to content

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.

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.

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:

  1. Loaded from a lock. The sample is packed, signed and loaded through the package loader from a screenplay.lock entry, and the model compiles against its contract.
  2. Lazy activation. Nothing is started when Stage starts. Reaching the NoticeBoard screen starts the Notifier backend, once.
  3. Invoked from a screen. The component’s invoke goes 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.
  4. 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.

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.

  • 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 authorize still applies.
  • Setting values from the model. The values behind setting <name> = ... and setting <name> from secret ... on a system are not read from the model yet; settings resolve from configuration under systems:<System>:<setting>.
  • Strings. $strings references in a component’s properties are not resolved into the element’s strings.