@cratis/stage.runtime 0.0.0 → 4.157.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cratis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
 # @cratis/stage.runtime
 
-Placeholder. Real versions are published by the Cratis/Stage release workflow.
+The Cratis Stage runtime renders Scene documents using Arc, Cratis Components and the default Scene blueprint.
+It shares React, Arc contexts and Scene's command registry with the consuming application through exact peer dependencies.
+
+Import `App` (also exported as `StageApplication`), `StageSourceProvider`, `staticStageSource` and the corresponding types from `@cratis/stage.runtime`.
+Wrap the application in `StageSourceProvider` with its content source. The live Stage host supplies HTTP transport;
+a built application can supply `staticStageSource({ scene, routes, strings })` instead.
+
+Use `styledPrimeReact` from `@cratis/stage.runtime/vite` in the consuming Vite configuration.
+The runtime imports its own CSS; `@cratis/stage.runtime/styles.css` also exposes it for host-only surfaces.
+
+The runtime's version follows the Stage release. Generated applications continue to receive the embedded runtime until the renderer switches to this package.

package/dist/src/App.d.ts

@@ -0,0 +1,65 @@
+import { type ApplicationStructure, type DialogTemplate, type InstanceContribution, type Layout, type NavigationModel, type SceneElement, type Screen, type ScreenTemplate, type Theme, type UiProfile, type ExposureDeclaration } from '@cratis/scene.model';
+import type { EffectiveNavItem, PackageCatalog } from '@cratis/scene.engine';
+import { type ComponentRegistry } from '@cratis/scene.react';
+import { type CompositionOptions } from '@cratis/scene.blueprint.default';
+import '@cratis/scene.blueprint.default/styles.css';
+import './app.css';
+export interface StageSceneApplication {
+    uiProfiles?: UiProfile[];
+    themes?: Theme[];
+    layouts: Layout[];
+    screenTemplates: ScreenTemplate[];
+    dialogTemplates?: DialogTemplate[];
+    screens: Screen[];
+    exposures?: ExposureDeclaration[];
+    instanceContributions?: InstanceContribution[];
+    /** The navigation regions of the application and its modules; absent when the model declares none. */
+    navigation?: NavigationModel;
+    /** The modules, features and slices navigation targets and toolbar slice buttons resolve against. */
+    structure?: ApplicationStructure;
+    /** The JSON schema of every modeled command, by name, which a toolbar slice's task dialog reads its fields from. */
+    commandSchemas?: Record<string, string>;
+}
+/**
+ * The registry a Stage renders with: Scene's core vocabulary, PrimeReact and the default blueprint, then any
+ * components the host adds, then the Stage's own table, action, form and chrome - which always win, because they
+ * are what reach the running application.
+ * @param components Components the host adds, such as a package an application composes with.
+ * @returns The registry.
+ */
+export declare function stageApplicationRegistry(components?: ComponentRegistry): ComponentRegistry;
+/**
+ * The shell the application starts in - the one the profile's root template names, resolved by the Scene engine against the
+ * default blueprint and the application's own templates, exactly as the Studio preview resolves it.
+ *
+ * @param scene The scene the Stage renders.
+ * @param screenTemplates The templates the approved domain blueprints bring.
+ * @returns The effective shell, with the engine's diagnostics.
+ */
+export declare function stageShellOf(scene: StageSceneApplication, screenTemplates?: ScreenTemplate[]): import("@cratis/scene.engine").EffectiveShell;
+/**
+ * What the Stage decides about composing a screen, on top of the composition it shares with the preview: its own chrome around the
+ * shell (the effective navigation regions are Scene's), its command form, its status line and its data sources.
+ */
+export declare function stageComposition(scene: StageSceneApplication, locales: string[], locale: string, packageCatalog?: PackageCatalog, dictionary?: Record<string, string>, blueprintTemplates?: ScreenTemplate[], showFooter?: boolean): CompositionOptions;
+/**
+ * Composes one screen the way the application shows it: the shared composition - the shell for the screen's layout, the chrome in
+ * its slots, the screen inside the template it names - with the Stage's own decisions.
+ */
+export declare function composeStageScreen(scene: StageSceneApplication, screen: Screen, locales: string[], locale: string, packageCatalog?: PackageCatalog, blueprintTemplates?: ScreenTemplate[]): SceneElement;
+export interface AppProps {
+    /** Components the host adds to the registry, beneath the Stage's own. */
+    components?: ComponentRegistry;
+    /**
+     * What each package the host adds components for declares, by package name. A name an authored screen gives as
+     * `Package.component`, or a bare name only such a package declares, resolves to the host's component through it.
+     */
+    packageCatalog?: PackageCatalog;
+    /** The screen templates the approved domain blueprints bring; a screen's `template blueprint ...` reference resolves to one of them. */
+    screenTemplates?: ScreenTemplate[];
+    /** The dialog templates the approved domain blueprints bring, which an authored dialog destination can open. */
+    dialogTemplates?: DialogTemplate[];
+    /** Hides a navigation item the user may not see - hidden, never disabled, so nothing about it leaks. */
+    isVisible?: (item: EffectiveNavItem) => boolean;
+}
+export declare function App({ components, packageCatalog, screenTemplates, dialogTemplates, isVisible }?: AppProps): import("react").JSX.Element;

package/dist/src/StageChrome.d.ts

@@ -0,0 +1,44 @@
+import { type ReactNode } from 'react';
+import type { ComponentRegistry, RegisteredComponentProps } from '@cratis/scene.react';
+/** What the Stage's own components need that the document itself does not carry. */
+export interface StageChromeState {
+    locales: string[];
+    locale: string;
+    setLocale: (locale: string) => void;
+    activity: string;
+}
+/** Provides {@link StageChromeState} to the Stage's own components. */
+export declare function StageChromeProvider({ state, children }: {
+    state: StageChromeState;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The name the status line is registered under. */
+export declare const stageActivityComponent = "Stage:activity";
+/** The language picker in the topbar, shown only when the model declares more than one. */
+export declare function StageLocale(): import("react").JSX.Element | null;
+/**
+ * The application's navigation as the hierarchy the model declared: a group per module and feature, nested as deep
+ * as the model nests them, each entry linking to the screen it opens.
+ */
+export declare function StageNavigationTree({ element }: RegisteredComponentProps): import("react").JSX.Element;
+/**
+ * The `core:outlet` the Stage renders: the screen the Scene navigation host placed in the named outlet, drawn
+ * inside the Stage's own data scope so its queries, selections and commands work as they do on a primary screen.
+ *
+ * Scene's own outlet renders the placed screen in a scope of its own, which cannot see what the Stage resolves
+ * queries and selections with, so the Stage draws the same region itself - including the `Close` button of an outlet the host
+ * put in a slot the shell declares (`slot side`).
+ */
+export declare function StageOutlet({ element }: RegisteredComponentProps): import("react").JSX.Element;
+/** What the last interaction did, or could not do. */
+export declare function StageActivity(): import("react").JSX.Element | null;
+/**
+ * Mirrors the active theme's colour scheme and page colors onto the document.
+ *
+ * The theme provider scopes its tokens to its own element, but PrimeReact portals a dialog or an overlay to
+ * `body`, outside that element, and the page behind the shell is `body` too. Without this, a dark theme would
+ * paint the shell dark, leave the page around it light and open every dialog light.
+ */
+export declare function ColorSchemeMirror(): null;
+/** The Stage's own components, to merge over the blueprint's. */
+export declare const stageChromeComponents: ComponentRegistry;

package/dist/src/StageCommandForm.d.ts

@@ -0,0 +1,18 @@
+import type { ExternalComponent } from '@cratis/scene.model';
+export interface SchemaProperty {
+    name: string;
+    type?: 'text' | 'number' | 'boolean' | 'date';
+    required: boolean;
+    unsupportedReason?: string;
+}
+interface StageCommandFormProps {
+    element: ExternalComponent;
+}
+/** Renders an authored screen form through Cratis Arc's native CommandForm boundary. */
+export declare function StageCommandForm({ element }: StageCommandFormProps): import("react").JSX.Element;
+/**
+ * The properties a command's JSON schema declares, with the type the native form gives each and whether it is required. A toolbar
+ * slice's task dialog is built from the same reading, so a command is the same fields wherever it is presented.
+ */
+export declare function schemaPropertiesOf(schema: string): SchemaProperty[];
+export {};

package/dist/src/StageCommandOutcome.d.ts

@@ -0,0 +1,11 @@
+/** What executing a modeled command came back with. */
+export interface StageCommandOutcome {
+    isSuccess: boolean;
+    response?: unknown;
+    validationErrors: {
+        member: string;
+        message: string;
+    }[];
+    /** Why the command did not run or failed, as a person should read it. Empty on success. */
+    messages: string[];
+}

package/dist/src/StageGuardedAction.d.ts

@@ -0,0 +1,20 @@
+import type { ExternalComponent } from '@cratis/scene.model';
+import type { InteractionHandlers } from '@cratis/scene.react';
+export interface StageGuardedActionProps {
+    element: ExternalComponent;
+    interactions?: InteractionHandlers;
+}
+/** Whether an element is an action authored with `when ... otherwise`. */
+export declare function isGuardedAction(element: ExternalComponent): boolean;
+/**
+ * Renders an action authored with `when <guard> execute <command> ... otherwise ...`.
+ *
+ * The guard is evaluated against the item on every render, so the action follows the data: a work item that is
+ * closed while the screen is open stops offering Close. The first alternative that holds is the command the action
+ * executes; when none holds, the authored `otherwise` decides - `hidden` renders nothing, `execute` offers its
+ * command instead. Without an item there is nothing to decide about, so nothing is offered.
+ *
+ * A guard this runtime cannot evaluate never lets a command through: the action is shown disabled with the
+ * diagnostic, which is the same refusal Stage reports when it admits the Scene.
+ */
+export declare function StageGuardedAction({ element, interactions }: StageGuardedActionProps): import("react").JSX.Element | null;

package/dist/src/StageShellSettings.d.ts

@@ -0,0 +1,15 @@
+import type { StageShellSettings } from './stageShell';
+/** The query that says the operating system prefers a dark scheme. */
+export declare const prefersDarkQuery = "(prefers-color-scheme: dark)";
+/** Whether the operating system prefers a dark scheme right now. */
+export declare function systemPrefersDark(): boolean;
+/**
+ * Starts the shell the way the profile says: its sidebar mode, its menu tint and the theme its colour scheme selects. The user can
+ * still switch theme or mode afterwards, as in the Scene preview; this is only what the application starts in.
+ *
+ * It renders nothing and sits inside the shell's layout configuration, so it speaks to the same provider the topbar's toggle does.
+ */
+export declare function StageShellSettingsApplier({ settings, onSystemSchemeChange }: {
+    settings: StageShellSettings;
+    onSystemSchemeChange?: (prefersDark: boolean) => void;
+}): null;

package/dist/src/app.css

@@ -0,0 +1,2 @@
+body{min-width:20rem;min-height:100vh;margin:0;font-family:system-ui,-apple-system,Segoe UI,sans-serif}button{font:inherit}.stage-message{text-align:center;place-content:center;min-height:100vh;padding:2rem;display:grid}.stage-activity{background:var(--layout-highlight,#eef2ff);border-radius:var(--layout-radius,.5rem);color:var(--layout-highlight-text,#3730a3);margin-top:1rem;padding:.75rem}.stage-locale{background:var(--layout-card,#fff);border:1px solid var(--layout-border,#e2e5e9);border-radius:var(--layout-radius,.5rem);color:var(--layout-text,inherit);padding:.35rem .5rem}.stage-table{background:var(--layout-card,#fff);border:1px solid var(--layout-border,#e2e5e9);border-radius:var(--layout-radius,.5rem);padding:.5rem}.stage-table table{border-collapse:collapse;width:100%}.stage-table th,.stage-table td{border-bottom:1px solid var(--layout-border,#e2e5e9);text-align:left;padding:.5rem .75rem}.stage-table th{color:var(--layout-text-muted,#6b7280);text-transform:uppercase;font-size:.85rem;font-weight:600}.stage-empty{color:var(--layout-text-muted,#6b7280);font-style:italic}.stage-note{color:var(--layout-text-muted,#6b7280);margin:0 0 .5rem}.stage-note--error{color:#dc2626}.stage-action{justify-items:start;gap:.75rem;display:grid}.stage-command-form__layout{gap:var(--layout-gap,1rem);width:100%;min-width:0;display:grid}.stage-command-form__field{min-width:0;display:block}.stage-form{background:var(--layout-card,#fff);border:1px solid var(--layout-border,#e2e5e9);border-radius:var(--layout-radius,.5rem);gap:.6rem;min-width:20rem;padding:1rem;display:grid}.stage-form label{gap:.25rem;display:grid}.stage-form span{color:var(--layout-text-muted,#6b7280);font-size:.85rem}.stage-form input{background:var(--layout-background,#fff);border:1px solid var(--layout-border,#e2e5e9);color:inherit;border-radius:.3rem;padding:.45rem .6rem}pre{background:var(--layout-background,#f4f5f7);border-radius:.4rem;padding:1rem;overflow:auto}[role=table] header{gap:1rem;font-weight:600;display:flex}.stage-dialog-backdrop{z-index:1000;background:#00000073;justify-content:center;align-items:center;display:flex;position:fixed;inset:0}.stage-dialog{background:var(--layout-card,#fff);border:1px solid var(--layout-border,#e2e5e9);border-radius:var(--layout-radius,.5rem);color:var(--layout-text,inherit);gap:.75rem;min-width:min(90vw,24rem);max-width:min(90vw,48rem);max-height:90vh;padding:1rem;display:grid;overflow:auto;box-shadow:0 1rem 3rem #0000004d}.stage-dialog>button{justify-self:end}
+/*$vite$:1*/

package/dist/src/blueprint.d.ts

@@ -0,0 +1,48 @@
+import type { SceneElement, Screen, UiProfile } from '@cratis/scene.model';
+import type { PackageCatalog } from '@cratis/scene.engine';
+import { type ComponentRegistry } from '@cratis/scene.react';
+/** The qualified name Stage registers its locale picker under. */
+export declare const stageLocaleComponent = "Stage:locale";
+/**
+ * The profile a scene renders against: the shared one - the model's own `ui profile` with the packages every host renders with
+ * admitted - with the PrimeReact widgets the default blueprint is built from between Scene's core and the blueprint, so the
+ * blueprint's component still wins a name both declare.
+ *
+ * @param profiles The profiles the scene declares.
+ * @returns The profile to resolve component names with.
+ */
+export declare function stageProfile(profiles: UiProfile[] | undefined): UiProfile;
+/** What each package declares, so a bare name resolves to the package that provides it. */
+export declare const stageCatalog: PackageCatalog;
+/** Every component the Stage can render: Scene's core, PrimeReact, the default blueprint's shell, and the template wrapper the shared composition places screens in. */
+export declare function stageRegistry(overrides: ComponentRegistry): ComponentRegistry;
+/**
+ * What every package the application renders with declares: the Stage's own packages, and the components of the
+ * custom packages the application approved.
+ *
+ * A custom package never replaces what a Stage package declares; it only adds its own entry.
+ *
+ * @param approved What each approved custom package declares, by package name.
+ * @returns The catalog component names are resolved against.
+ */
+export declare function stageCatalogWith(approved: PackageCatalog | undefined): PackageCatalog;
+/** The qualified name Stage registers its navigation tree under. */
+export declare const stageNavigationTreeComponent = "Stage:navigationTree";
+/** The name the application shows in its topbar and sidebar when the model gives it no logo. */
+export declare const stageApplicationName = "Cratis Stage";
+/**
+ * The chrome the blueprint's application shell wraps every screen in, besides the screen itself.
+ *
+ * When the model declares navigation regions, the topbar and sidebar draw the *effective* navigation of the module the user is in
+ * (Scene's regions: inherit, extend, override) and nothing here lists items. A model that declares none keeps what it always had:
+ * the entries its screens authored as `Navigation` contributions - or one flat list of its screens - as the menu, and the topbar and
+ * sidebar draw no region of their own.
+ */
+export declare function applicationChrome(screens: Screen[], activeScreen: string, locales: string[], locale: string, application?: {
+    title: string;
+    image?: string;
+}, regions?: boolean, showFooter?: boolean): Record<string, SceneElement[]>;
+/** The hash a screen is addressed by - what the blueprint's breadcrumb links point at. */
+export declare function screenHash(name: string): string;
+/** The screen name a hash addresses, or undefined when it addresses none. Parameters after `?` are not part of it. */
+export declare function screenFromHash(hash: string): string | undefined;

package/dist/src/commandExecutor.d.ts

@@ -0,0 +1,11 @@
+import { type ArcConfiguration } from '@cratis/arc.react';
+import { Command, type ICommandResult } from '@cratis/arc/commands';
+import type { StageCommandOutcome } from './StageCommandOutcome';
+/** Resolves only native Arc command proxies; unrelated registry entries cannot execute. */
+export declare function registeredCommand(name: string, typeName?: string, route?: string): (new () => Command) | undefined;
+/** Executes the registered proxy with the same host configuration as Arc's useCommand. */
+export declare function executeRegisteredCommand(name: string, values: Record<string, unknown>, arc: ArcConfiguration): Promise<StageCommandOutcome>;
+/** Maps Arc's typed result without treating a rejection or authorization failure as success. */
+export declare function commandOutcome(name: string, result: ICommandResult): StageCommandOutcome;
+/** The command executor for interactions, guarded actions and slice task dialogs. */
+export declare function useStageCommandExecutor(): (name: string, values: Record<string, unknown>) => Promise<StageCommandOutcome>;

package/dist/src/index.d.ts

@@ -0,0 +1,11 @@
+export { App, App as StageApplication, composeStageScreen, stageApplicationRegistry, stageComposition, stageShellOf } from './App';
+export type { StageSceneApplication } from './App';
+export { StageSourceProvider, staticStageSource, useStageSource, stageEndpoints } from './stageSource';
+export type { StageSource, StageStaticContent } from './stageSource';
+export type { StageRoutes } from './stageRoutes';
+export { stageTheme, stageDarkSelector } from './stageTheme';
+export { executeRegisteredCommand, registeredCommand, useStageCommandExecutor } from './commandExecutor';
+export { StageCommandForm } from './StageCommandForm';
+export { StageGuardedAction } from './StageGuardedAction';
+export { StageDataProvider, useStageData, useStageQuery, dataChanged } from './stageData';
+export { createStageSliceInvoker, sliceFieldsFrom } from './stageSlices';