Run extension components
An extension can bring frontend components as well as a backend. A screen places one with component <System>.<Component>, and Stage serves it
the things the
extension component contract promises it. This page covers the
server side of that: what reaches the browser, and what a component may ask Stage to do. To build a component, see
Build an extension component.
Where the catalog of placements comes from, and how a model reaches a running extension, is on From a model to a running extension.
The browser half runs in the Stage runtime on @cratis/scene.extensions, at the Scene release Stage is built on. A screen’s component is a Stage:extensionComponent element, and the
runtime loads its frontend, builds the contract’s context and renders or mounts it. See In the browser.
Public settings only
Section titled “Public settings only”A system’s setting is public or secret, never both. The component’s context carries the public settings and nothing else:
- A secret is not read, not named and not listed. It reaches a backend only through
GetSecret(see Host services). - A value nobody declared is never sent.
- Settings are those of the component’s own system.
GET /stage/extension-components/Orders/Slack/ChannelPicker/settings{ "settings": { "workspace": "acme" } }The route is /stage/extension-components/<Screen>/<System>/<Component>. It answers 404 when the screen does not place that component.
Invoking an ability from the browser
Section titled “Invoking an ability from the browser”POST /stage/extension-components/Orders/Slack/ChannelPicker/invokeContent-Type: application/json
{ "ability": "Send", "interaction": "click-1", "input": "{\"channel\":\"ops\"}" }Stage checks the request in this order and stops at the first refusal:
| Check | Refusal | Status |
|---|---|---|
| The screen places the component | NotPlaced |
404 |
The contract’s invokes allowlist names the ability |
NotAllowed |
403 |
| The person is authenticated and satisfies the screen’s policy | Forbidden |
401 or 403 |
| The ability path admits the invocation | Refused |
400 |
Only then is the invocation recorded and run on the same path a reaction or a workflow uses, with the origin kind ScreenInteraction. The
request waits for the outcome (30 seconds, set with BrowserInvocationOptions) and answers 200 with the outcome and output when it settles,
or 202 with the invocation identity when it does not.
The interaction is chosen by the browser and is the invocation identity of that interaction. Asking again with the same one, for a retry or a
double click, finds the invocation that exists and does not do the effect twice. The person is part of the cause, so one person’s interaction can
never find another’s.
In the browser
Section titled “In the browser”The Stage runtime places a component from an element with these properties:
| Property | Meaning |
|---|---|
system, component |
The system and the component’s name in its contract. The module must export the component under this name. |
screen |
The screen that places it. The screen being shown when absent. |
kind |
react or mount, as the model says. The module’s definition must be the same kind, or the placeholder says which of the two is wrong. |
module |
The address of the extension’s frontend module, served from the locked package (extension-assets/{id}/…, see Packages). |
properties |
The properties the component is given. |
invokes, signals |
The abilities it may invoke and the signals it may raise, from the contract. |
strings |
The strings of the screen, by key. |
placeholder |
The address of the component’s placeholder, shown in a frame that cannot run script until the component is ready. |
React components are rendered in Stage’s own React tree, inside Scene’s ExtensionContextProvider, so the useUser, useTenant, useLocale,
useTheme, useSettings, useStrings, useInvoke, useRaise and useTrigger hooks work. They share React with Stage: react, react-dom and
@cratis/scene.extensions are on the import map of the page, so an extension that imports them by name gets Stage’s copy (see
Custom packages). Mount components (Vue, Svelte, Lit, web
components, plain DOM) are given a host element, their properties and the context, and are updated and unmounted with the screen.
The context is made of:
| Part | From |
|---|---|
user |
Arc’s identity endpoint (.cratis/me): who the person is and the roles they hold. |
tenant |
The tenant the identity names, or default. |
locale |
The language the Stage shows and its available languages, and the browser’s time zone. Changing the language updates the context. |
theme |
Whether the page is light or dark, and the --cratis-* design tokens in force. A change of theme updates the context. |
settings |
The public settings of the component’s system, read from the settings endpoint above. |
strings |
The strings of the element. |
invoke |
The invoke endpoint above, on one interaction identity kept across the waits, so asking again never invokes twice. An ability outside invokes is refused in the browser as well as by the host, and a refusal arrives as an ExtensionInvocationError with the status and the reason the host gave. |
raise |
A signal in signals. It runs the screen’s on <signal> interactions (see Handling a raised signal), reaches the onSignal of StageExtensionServicesProvider and is dispatched as a bubbling stage-extension-signal event on the component’s element. |
on |
A trigger sent to the component’s element as a stage-extension-trigger event, with detail { name, values }. |
Secrets never reach the browser. The only requests a component’s page makes are the identity, the public settings and invocations, and an invocation carries the ability, the interaction identity and the inputs the component gave, and nothing else. The credentials and the secret settings stay on the host, which runs the ability.
Handling a raised signal
Section titled “Handling a raised signal”A screen handles a signal with on <signal> on the component it places, and reads what the signal carried as signal.<value>:
component Notifier.NoticeBoard board on dismissed execute DismissNotice with noticeId from signal.noticeIdThe model writes on <signal> as an application trigger, so the host decides what it is. When the name is a signal the component’s contract declares,
Stage binds the interaction to Scene’s signal trigger (SignalInteractionTrigger, serialized as { "signalName": "dismissed" }); a name the contract
does not declare stays the application trigger it is. When the component raises the signal, the runtime resolves the behaviors attached to that
component with resolveSignalBehaviors and runs them with the Scene interaction engine, the same engine that runs every other interaction. A
signal.<value> argument reads the value the component raised the signal with, every other path is the screen’s own, and the data is read again
once the interaction has run. A signal never starts an application trigger of the same name, and the reverse. The contract is on
Binding a raised signal to a screen interaction.
Stage depends on one Scene release for every Scene package, and on @cratis/components 4.40.1, which that release requires. The Notifier sample’s
contract.play declares the dismissed signal, and the
end-to-end specification raises it.
Static placeholders
Section titled “Static placeholders”A page without a browser runtime (a preview, an export, the first paint) cannot run a component. ExtensionComponentPlaceholder renders an element
that names the component and how it is hosted, aria-busy, and nothing from the context:
<div data-stage-extension-component="Slack.ChannelPicker" data-kind="mount" role="region" aria-label="Slack.ChannelPicker" aria-busy="true"></div>See also
Section titled “See also”- Extension backends and the host services reference
- Extension component contract and building a component in Scene
- Screens in Screenplay, where a screen places a component
- Custom packages