Building and consuming extension packages
An extension package is the code and contract that realizes a Screenplay system. The model names what the business can ask (abilities, triggers, components); the package carries how. Do not invent package behavior: the contract below is the Screenplay documentation, and the tooling is the Cratis CLI. If a fact is not on a linked page, say so instead of guessing.
Pages to read first
- Screenplay extension contracts: the contract file, manifest, settings, components, the
extensionreference, the lock, the cache and restore, provider compatibility. - Screenplay systems and abilities and environments.
- Screenplay screens: extension components and the command line
restore. - Stage extension backends (protocol, SDKs for C#, Kotlin, Go and TypeScript, host services), packages and execution tiers and activation.
- Scene extension component contract: how a frontend component registers and what conformance checks.
- Cratis CLI manage extension packages,
extension new,extension verify,restore,updateandvendor.
Author a package
- Scaffold, do not hand-roll.
cratis extension new -n <Name> [--kind extension|package] [--backend csharp|kotlin|go|typescript|none] [--frontend react|mount|screenplay|none] [--component react|mount] [--publisher <name>]. The result already has acontract.play, builds and passescratis extension verifywithout edits. In an AI agent or with redirected output it never prompts; it uses flags and defaults.--dry-runlists files without writing. The templates areCratis.Templates.Extensions(cratis-extension,cratis-extension-package) from Cratis/Templates. - Choose the kind.
extensionis an OCI artifact (contract, optional backend, optional frontend).packageis an npm package with frontend components only and no backend. An extension with neither backend nor frontend that only declares abilities is valid. - Write the contract (
contract.play): a manifest (display name,description,iconrequired, elsePLAY0999;image,requires stage|screenplay|platform|runtime,activation), thensetting,ability(same grammar as systems),trigger,componentandbackend runtime <name> <version> assembly "<file>"/frontend "<path>". Contents are read from their declarations; never restate them in the manifest. Types resolve in the consuming model's scope. - Settings.
setting <name> [public | secret].publicmay reach a browser;secretnever does; both isPLAY1103; neither stays with the backend. - Components.
kind react | mount | screenplay(elsePLAY1100),platform,placeholder "<path>"(required forreactandmount,PLAY1102), typedpropertylines,raises <signal>with typed values, andinvokes <Ability>for abilities the component may call through the host (must be declared,PLAY1104). A placeholder is static HTML: no script, inline event handler,javascript:URL or external reference, styles inline and images asdata:URIs (PLAY1113). - Backend. Stage hosts backends outside its own process over a two-way gRPC protocol; the backend asks Stage for settings, secrets and telemetry through host services. Tier is chosen by Stage (
None,SharedHost,Native,Container) from the contract's runtime. A backend is told its address, system and package digest bySTAGE_EXTENSION_*environment variables. Read the Stage SDK page for the language chosen. - Frontend. A frontend component registers as its declared kind and must pass the Scene conformance kit; use the Scene contract page, not memory. A signal it raises runs the screen's
on <signal>interaction (a SceneSignalInteractionTrigger, bound by Stage); see handling a raised signal. - Same name twice (abilities, triggers, components, settings, ignoring case) is
PLAY1105; anything else unrecognized in the file isPLAY0998.
A .extensionignore in the package folder names what the build does not ship (sources, specifications, scripts) so verify can tell it from what ships.
Verify before publishing
cratis extension verify [TARGET] [--range <r>] [--baseline <folder>] [--strict] [--format table|json]. TARGET is a package folder (default current directory), a contract.play, or a package reference. Checks always appear with a status: passed, failed, skipped (could not run; never a pass; --strict fails it) or notapplicable. The checks are contract, manifest, contents, placeholders, frontend and backend. The frontend and backend checks report EXTV060 and EXTV070 where they cannot run yet; read what the CLI page says does not run yet and report that honestly, never as green.
Consume a package from a model
system Payments
extension "cratis/stripe" version 2
setting secretKey from secret StripeSecretKey
- A system that names an extension declares no abilities of its own (
PLAY1106); it gets the contract's abilities, and the contract's triggers become<System>.<Trigger>for reactions. - A reference is a catalog short name (
owner/nameresolves toghcr.io/owner/extension-name), a full OCI reference, ornpm:<package>for frontend-only packages.version 2is the latest 2.x,2.3.1exactly,"^2.3"and"~2.3"as in semver. - The lock.
screenplay.lockbeside the model root pins each reference (range, resolved reference, version, packagedigest,contracthash,publisher). Commit it. The compiler never resolves a range; it reads the contract by locked digest from the vendoredextensionsfolder, then the user cache (SCREENPLAY_EXTENSION_CACHE). Unlocked isPLAY1107, range mismatchPLAY1110, not restoredPLAY1108, contract differs from the hashPLAY1109, malformed lockPLAY1111. The language server and MCP downgrade some to warnings and restore on opening a model root. - Restore, update, vendor.
cratis extension restorefills the cache from the lock and pins what is missing;cratis extension updatemoves references to the newest release in range and shows how each contract changes;cratis extension vendorcopies every locked package to a folder or private registry for offline use.--lockedis for CI and never pins. Shared options:--root,--source <folder|oci://host/prefix>,-e <environment>,-o <format>.screenplay restorein the Screenplay tool restores from a directory without network. - Trust. Naming a package is not trusting it. The CLI requires a valid signature for exactly the package digest and a publisher in the committed
.cratis/extensions.jsonallow-list. An interactive terminal may ask once; CI and AI agents cannot ask and failUnallowed. Never edit the allow-list or accept a publisher to make a command pass without the user's say; a changed key is reviewed, never auto-trusted. - Exit codes of the extension commands:
0ok,1not found,2registry unreachable,4credentials refused or missing,5not locked, unallowed, unsigned, mismatched or incompatible. - Registry credentials live in the selected environment (
extensions.registry.<host>.tokenor.usernameand.password, as secrets), never in the model or lock. See environments and secrets. - Swapping providers. A replacement must offer the same abilities, triggers, components, properties and signals with the same typed shape; mismatches are reported at each use (
PLAY1112, unknown ability).
Configure and run
Settings, named secrets and activation are set in the model and supplied by the environment; see environments and secrets. cratis run <model> -e <environment> admits the model's locked extensions and hands the Stage their settings and secrets; read the CLI run page.
Boundaries
- Declaring a system and invoking its abilities from the model is automations and translations.
- Placing a package component on a screen is UI composition.
- Do not publish, push to a registry or change an allow-list unless the user asked for that effect.