Cratis Arc embedded event model: browse your application
Cratis Arc’s embedded event-model explorer lets you browse the commands, events, and read models recovered from your application’s source. The build embeds generated Screenplay documents, text files describing that model, and Cratis.Arc.Screenplay.Embedded serves them as a read-only board at /.cratis/event-model. Use it to understand a feature without maintaining a separate diagram.
The explorer reads embedded documentation, not stored events or live application data. Its view reflects the source used for the build and the constructs the generator can recover.
Quickstart
Section titled “Quickstart”-
Add the package to your ASP.NET Core application (skip this if you already reference the
Cratismetapackage):Terminal window dotnet add package Cratis.Arc.Screenplay.Embedded -
Map the viewer after
builder.Build()and beforeapp.Run():if (app.Environment.IsDevelopment()){app.MapCratisEventModel();}With the
Cratismetapackage, your existingAddCratis/UseCratissetup does this automatically for a Debug build running in Development; no explicit mapping is needed. -
Run in Development and open
http://localhost:<port>/.cratis/event-model/, using the port printed by your application:Terminal window dotnet run --configuration Debug -- --environment Development
See Security before exposing the viewer beyond your local development machine.
Select a feature to follow its commands through events to read models, or open the assembly document for the wider model. The explorer uses the same analysis as Screenplay generation; check that page’s supported constructs and diagnostics when something you expect is absent.
Arc does not require event sourcing. An ordinary command that returns a response has no event card. Commands that produce recognized Chronicle events show those events, including events declared in another slice; state-view slices show the events they consume.
Open the explorer in a Cratis application
Section titled “Open the explorer in a Cratis application”The Cratis metapackage includes the embedded-generation package. In an existing ASP.NET Core host configured with AddCratis and activated with UseCratis, build and run in Debug with the hosting environment set to Development, then open /.cratis/event-model/. The build creates and embeds the documents automatically; UseCratis maps the viewer automatically only when both conditions hold.
The build check uses the application’s DebuggableAttribute and whether optimizations are disabled. Production, Staging, and other environments do not expose the viewer automatically, even for a Debug build. Release-built applications do not expose it automatically, even in Development. Through the metapackage, Release builds also disable generation by default.
To opt out, configure services before building the host:
builder.Services.AddCratisEventModelViewer(options => options.Enabled = false);For Arc-only hosts, or when you want to choose the exposed assemblies and policy yourself, use the explicit setup below.
Map the explorer explicitly
Section titled “Map the explorer explicitly”In an ASP.NET Core application that already declares Arc commands or queries, add the package:
dotnet add package Cratis.Arc.Screenplay.EmbeddedMap the explorer in your existing Program.cs after building the application. This is a complete minimal host; retain your application’s existing Arc setup when adding the mapping:
var builder = WebApplication.CreateBuilder(args);var app = builder.Build();
if (app.Environment.IsDevelopment()){ app.MapCratisEventModel();}
app.Run();Build and start your application, then open /.cratis/event-model/. Select a document in the hierarchy to view its event-model board or its generated .play source. The viewer is bundled in the package; your application’s users do not need to install Node.js.
Outside automatic metapackage hosting, nothing is mapped until you call the extension. By default it reads the entry assembly. For an application whose model lives in other assemblies, select them explicitly:
app.MapCratisEventModel(typeof(MyApplicationMarker).Assembly);MyApplicationMarker is a type in the assembly containing your application artifacts. Each selected assembly must have been built with the embedded-generation package enabled. Documents remain assembly-scoped; this does not merge multiple projects into one model.
Keep it out of release builds
Section titled “Keep it out of release builds”Decide separately whether a build should contain model documents and whether the application should serve them. Removing the endpoint mapping prevents requests to the explorer; it does not remove resources already embedded in the assembly.
To generate documents only in Debug, add this to your application project:
<PropertyGroup> <CratisEmbeddedScreenplayEnabled Condition="'$(Configuration)' != 'Debug'">false</CratisEmbeddedScreenplayEnabled></PropertyGroup>A direct reference to Cratis.Arc.Screenplay.Embedded enables generation by default; the Cratis metapackage disables it in Release unless you explicitly set CratisEmbeddedScreenplayEnabled to true. Generation does not run during design-time builds. A real build regenerates the resources from the current source. When none of the sources, references, analyzers or settings they are generated from changed since the last build, the previous output is reused and the application is not analyzed again; a build that reported a warning always runs again so the warning is shown again. Disabling generation prevents previously generated files from being included.
Cap validated generation for an older consumer
Section titled “Cap validated generation for an older consumer”The embedded generator uses the same validated-generation admission as standalone Screenplay generation. String-backed strategies with fully recoverable concept rules need v20 of Screenplay’s executable semantic model (ESM). To keep documents below that boundary for an older consumer, set:
<PropertyGroup> <CratisEmbeddedScreenplayMaximumExecutableModelVersion>19.0</CratisEmbeddedScreenplayMaximumExecutableModelVersion></PropertyGroup>This preserves the validator but withholds validated generation and dependent mappings, responses and
pins. Diagnostics name the required version and the configured cap. Use 20.0, or leave the property
unset, to admit supported V20 contracts. Authoring-only output respects the same boundary; it does not
make opaque or refuted validation executable. A custom host sets
EmbeddedDocumentOptions.MaximumExecutableModelVersion to SemanticVersion.V19 or SemanticVersion.V20
for the corresponding behavior. See Validated generation
for proof diagnostics, UUID validation limits and fixture handling.
Compiler features and generated source
Section titled “Compiler features and generated source”Embedded generation forwards the build’s Features, InterceptorsNamespaces, and legacy InterceptorsPreviewNamespaces properties to its C# compilation and source-generator driver. This includes namespaces enabled by SDK features such as OpenAPI interceptors; you do not need to disable embedded generation or remove source generators.
Features uses Csc’s semicolon-, comma-, or space-separated feature syntax. The two interceptor namespace properties are combined as a semicolon-separated list. An explicit InterceptorsNamespaces entry in Features takes precedence over that combined list, matching Csc. Keep these settings on your application project; there is no separate embedded-generation override.
Custom build hosts can supply the same values through the Features, InterceptorsNamespaces, and InterceptorsPreviewNamespaces task parameters, or through the corresponding parameters of the SourceCompilation.Create overload. The existing overload remains available for callers without compiler features.
Understand the hierarchy
Section titled “Understand the hierarchy”Namespace placement is relative to your project’s RootNamespace. Set it explicitly when your assembly name and application namespace differ:
<PropertyGroup> <RootNamespace>Company.Library</RootNamespace></PropertyGroup>For example:
| Namespace | Placement |
|---|---|
Company.Library.Catalog.Authors.Registration |
Module Catalog, feature Authors, slice Registration |
Company.Library.Catalog.Books.Listing |
Module Catalog, feature Books, slice Listing |
Company.Library.Accounts.SignIn |
Rooted feature Accounts, slice SignIn |
The first segment after the root is a module when it contains feature namespaces beneath it. If its children are only namespaces identified as slices, it is a rooted feature rather than a module. Nested features remain nested. The assembly document includes everything; scoped documents describe the selected module or feature and its descendants.
Screenplay’s current grammar requires a module container around features. Rooted features use the application’s root container in the .play text; they remain direct children of the assembly in the explorer rather than being promoted to modules.
Slice identification comes from recognized application artifacts, not a fixed list of folder names. Shared supporting types do not turn an arbitrary namespace into a slice. Cross-scope event references remain explicit dependencies in scoped documents.
Security
Section titled “Security”With the metapackage’s default automatic hosting, the viewer is exposed only for a non-optimized (Debug) build running with IHostEnvironment.IsDevelopment(). A Debug build deployed to Production or Staging does not expose it automatically.
Explicit app.MapCratisEventModel() calls work in every environment and bypass the automatic exposure options. To opt in deliberately outside Development, apply your application’s authorization policy to the returned route group:
app.MapCratisEventModel().RequireAuthorization("Developers");This assumes your host has already registered authentication and the Developers policy. The group protects the viewer, static assets, and every document query together. Explicit and automatic mapping reuse the same group, so adding authorization does not create a second unprotected copy.
To opt into automatic hosting outside Development, explicitly enable it and configure the same policy during service registration:
builder.Services.AddCratisEventModelViewer(options =>{ options.Enabled = true; options.RequireAuthorization = true; options.AuthorizationPolicy = "Developers";});Enabled = true explicitly opts into automatic hosting for any build and environment; it does not add authorization or generate documents. Set CratisEmbeddedScreenplayEnabled to true as well if you want resources in Release. Assemblies lets you name additional application assemblies; automatic selection otherwise uses the entry assembly and its already-loaded, directly referenced application assemblies, not framework assemblies or arbitrary loaded libraries.
Explore the model
Section titled “Explore the model”Choose an assembly, module, or feature in the sidebar to open its read-only board. The board initially fits the selected model. Use the lower-right toolbar to adjust zoom or the minimap, then pan to the slice you want to inspect; the initial fit does not keep resetting your view.

Open View in the upper right to choose:
- Full or Overview detail level.
- Properties to show or hide card properties.
- Arrows or Lines visualization.
These choices are stored in your browser’s local storage and restored on the next visit. If the browser blocks persistence, the viewer applies the choice but displays a warning that it could not remember it.
Each slice shows the specifications the document declares for it, in declaration order. A specification is drawn as cards: the events given before it, what it does, the events it expects and the errors it expects (then denied appears as an error named denied). What it does is the slice’s own command when it runs it, with the values it sets; any other action is named for its kind, such as append AuthorRegistered or clock 2026-10-05T08:00:00Z, with its values. An event stated for a source carries that source in its card’s name.
What a specification states that has no card travels in its header, after its name: the caller, the clock, generated values, read models given or expected, read models expected to be absent, the response then returns expects, query results, operations, and stream routes. Use the header alongside the cards to read the specification’s declared context and expectations. These are declarations, not test results: the board does not run specifications.

Choose Source to inspect the generated Screenplay for the selected document, highlighted the way the Screenplay editor shows it. The source is read-only because it is generated from your code. This is useful when a conversion warning says a declaration or mapping cannot be represented on the board.

Query the documents
Section titled “Query the documents”All paths below are relative to /.cratis/event-model/:
| GET path | Response |
|---|---|
hierarchy |
Selected projects and their document hierarchy |
documents/{projectId}/{documentId}/source |
Generated .play text |
documents/{projectId}/{documentId}/model |
Read-only canvas model with conversion warnings |
Use the IDs returned by hierarchy and URL-encode each path segment. Unknown projects, documents, and assets return HTTP 404. These queries read embedded resources only; they do not accept filesystem paths or fetch remote documents.
The board is a visualization, not another inference engine. Where its card model cannot show everything a Screenplay document expresses, conversion warnings make that limitation visible. Use the source view for the full generated document. Generation errors fail the build instead of embedding a document that the Screenplay compiler rejects.
Serve the explorer from another host
Section titled “Serve the explorer from another host”You can reuse the explorer without mapping routes in the application being inspected. For example, the Cratis CLI’s cratis view serves the viewer over documents read from a built assembly or generated in memory. A custom host can use the same types:
| Type | Package | Role |
|---|---|---|
EventModelCatalog |
Cratis.Arc.Screenplay.Embedded |
Reads catalogs and document sources from assemblies or from any IEventModelResources |
AssemblyEventModelResources |
Cratis.Arc.Screenplay.Embedded |
The manifest resources of an assembly built with this package |
InMemoryEventModelResources |
Cratis.Arc.Screenplay.Embedded |
The same resources, held in memory under the names an assembly embeds them as |
EventModelExplorer |
Cratis.Arc.Screenplay.Embedded |
Answers the hierarchy, a document’s source, and the board model it compiles to |
EmbeddedViewerAssets.Viewer |
Cratis.Arc.Screenplay.Embedded |
The viewer’s own page and assets |
EmbeddedDocumentGenerator |
Cratis.Arc.Screenplay.Embedded.Generation |
Generates the documents the build would embed, from one or more Roslyn compilations |
The following example generates the documents from compilations you have already loaded, without writing any files, and builds an explorer over them:
using Cratis.Arc.Screenplay.Embedded.Generation;using Cratis.Arc.Screenplay.Embedded.Hosting;using Cratis.Arc.Screenplay.Embedded.Hosting.Catalog;using Microsoft.CodeAnalysis;
public static class InMemoryExplorer{ public static EventModelExplorer For(IReadOnlyList<Compilation> compilations, string assemblyName, string rootNamespace) { var generation = new EmbeddedDocumentGenerator().Generate(compilations, new EmbeddedDocumentOptions(assemblyName, rootNamespace)); var catalog = EventModelCatalog.For([generation.ToResources(assemblyName)]);
return new EventModelExplorer(catalog); }}For documents an assembly already embeds, use EventModelCatalog.For([assembly]) instead of generating them.
To serve the viewer, answer GET requests relative to the page the viewer is served from: the page itself from EmbeddedViewerAssets.Viewer.TryReadIndex, assets/{path} from TryRead, and the three paths in Query the documents from EventModelExplorer. Serialize models with EventModelJson.SerializerOptions so the board can read them.