@cratis/scene.react 4.11.0 → 4.13.0

package/navigation/diagnoseRenderedNavigation.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationDiagnostic, NavigationGraph, diagnoseNavigation } from '@cratis/scene.engine';
+import { navigationRouteKey } from './navigationRouteKey';
+
+/**
+ * Diagnoses navigation the way this renderer routes it: the engine's checks, with duplicate routes compared
+ * by the URLs `resolveDestination` actually builds - identity-derived routes included, parameter spellings
+ * treated as equal.
+ */
+export function diagnoseRenderedNavigation(graph: NavigationGraph): NavigationDiagnostic[] {
+    return diagnoseNavigation(graph, navigationRouteKey);
+}

package/navigation/identityRoute.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationReference } from '@cratis/scene.model';
+
+/**
+ * The route a destination gets when no route override was authored: its screen name, or its stable
+ * module/feature/slice identity as a path.
+ */
+export function identityRoute(destination: DestinationReference): string | undefined {
+    if (destination.screen) return destination.screen;
+    const parts = [destination.module, destination.feature, destination.slice].filter((part): part is string => typeof part === 'string' && part.length > 0);
+    return parts.length ? parts.join('/') : undefined;
+}

package/navigation/index.ts

@@ -5,3 +5,6 @@ export * from './DestinationResolution';
 export * from './SceneNavigationContext';
 export * from './SceneNavigationHost';
 export * from './resolveDestination';
+export * from './diagnoseRenderedNavigation';
+export * from './identityRoute';
+export * from './navigationRouteKey';

package/navigation/navigationRouteKey.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationRouteKey } from '@cratis/scene.engine';
+import { identityRoute } from './identityRoute';
+
+/**
+ * The route a destination occupies in this renderer: the authored override or the identity-derived route -
+ * the same base `resolveDestination` builds a URL from - with surrounding slashes removed and every parameter
+ * placeholder (`{id}` or `:id`) reduced to one marker, so `/invoices/{id}` and `invoices/:invoiceId` are the
+ * same URL.
+ */
+export const navigationRouteKey: NavigationRouteKey = destination => {
+    const route = destination.route ?? identityRoute(destination);
+    if (!route?.trim()) return undefined;
+    return route
+        .trim()
+        .split('/')
+        .filter(segment => segment.length > 0)
+        .map(segment => (/^\{[^}]*\}$/.test(segment) || /^:.+$/.test(segment) ? '{}' : segment))
+        .join('/');
+};

package/navigation/resolveDestination.ts

@@ -4,6 +4,7 @@
 import { BindingScope, resolveBindingExpression } from '@cratis/scene.engine';
 import { DestinationKind, DestinationReference } from '@cratis/scene.model';
 import { DestinationResolution } from './DestinationResolution';
+import { identityRoute } from './identityRoute';
 
 /**
  * Resolves a destination into a renderer-neutral navigation action, deep link and target outlet/dialog.
@@ -27,12 +28,6 @@ export function resolveDestination(destination: DestinationReference, scope: Bin
     };
 }
 
-function identityRoute(destination: DestinationReference): string | undefined {
-    if (destination.screen) return destination.screen;
-    const parts = [destination.module, destination.feature, destination.slice].filter((part): part is string => typeof part === 'string' && part.length > 0);
-    return parts.length ? parts.join('/') : undefined;
-}
-
 function appendParameters(route: string, parameters: readonly (readonly [string, string])[]): string {
     if (!parameters.length) return route;
     let replaced = route;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.react",
-    "version": "4.11.0",
+    "version": "4.13.0",
     "description": "The React renderer implementing Scene.Engine's Renderer contract against real React/DOM.",
     "keywords": [
         "cratis",
@@ -51,12 +51,12 @@
         "build-storybook": "storybook build"
     },
     "dependencies": {
-        "@cratis/scene.engine": "4.11.0",
-        "@cratis/scene.model": "4.11.0"
+        "@cratis/scene.engine": "4.13.0",
+        "@cratis/scene.model": "4.13.0"
     },
     "devDependencies": {
-        "@cratis/scene.engine": "4.11.0",
-        "@cratis/scene.model": "4.11.0",
+        "@cratis/scene.engine": "4.13.0",
+        "@cratis/scene.model": "4.13.0",
         "@storybook/addon-links": "^10.6.1",
         "@storybook/react": "^10.6.1",
         "@storybook/react-vite": "^10.6.1",

package/packages/DesignTimeActionOutcome.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEdit } from '@cratis/scene.model';
+
+/**
+ * What running a design-time action did. A batch is submitted to the host whole or not at all.
+ */
+export interface DesignTimeActionOutcome {
+    /** Whether the edit batch was submitted to the host through `submitAction`. */
+    submitted: boolean;
+
+    /** The canonical edits the action produced. */
+    edits: SceneEdit[];
+
+    /** The action's own diagnostics, and any reason the batch was not submitted. */
+    diagnostics: string[];
+}

package/packages/DesignTimeActionState.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DesignTimeActionDescriptor } from '@cratis/scene.model';
+
+/**
+ * One design-time action as a designer presents it, with the visibility and enablement its owning package
+ * decided. An action without a loaded handler is shown disabled, with the reason.
+ */
+export interface DesignTimeActionState {
+    descriptor: DesignTimeActionDescriptor;
+
+    /** The package that owns the handler. */
+    package: string;
+
+    visible: boolean;
+    enabled: boolean;
+
+    /** Why the action is unavailable, when it is. */
+    diagnostic?: string;
+}

package/packages/DesignTimeContractVersion.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The design-time extension contract this host implements, as `major.minor`.
+ *
+ * The contract is the set of extension points a package's design-time bundle fills - previews, designers,
+ * property editors, property displays and actions - and the props and context each receives. A minor
+ * version adds optional members; a major version changes or removes them. A host loads a package's
+ * contributions only when the package's declared major version matches this one.
+ */
+export const DesignTimeContractVersion = '1.0';

package/packages/DesignTimeExtensionPoint.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The versioned design-time extension points a package can fill. The values are the keys shared by
+ * `PackageDesignTimeMetadata` (what a manifest declares) and `DesignTimeBundle` (what a bundle provides).
+ */
+export enum DesignTimeExtensionPoint {
+    Preview = 'previews',
+    Designer = 'designers',
+    PropertyEditor = 'propertyEditors',
+    PropertyDisplay = 'propertyDisplays',
+    Action = 'actions',
+}
+
+/** How a diagnostic names an extension point. */
+export const designTimeExtensionPointLabels: Record<DesignTimeExtensionPoint, string> = {
+    [DesignTimeExtensionPoint.Preview]: 'preview',
+    [DesignTimeExtensionPoint.Designer]: 'designer',
+    [DesignTimeExtensionPoint.PropertyEditor]: 'property editor',
+    [DesignTimeExtensionPoint.PropertyDisplay]: 'property display',
+    [DesignTimeExtensionPoint.Action]: 'action',
+};

package/packages/DesignTimeResolution.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a design-time host found for one extension point request.
+ *
+ * When `contribution` is absent the host renders its generic fallback - the default preview, the
+ * descriptor-driven inspector, the default editor for the property's value type - and `diagnostic` says
+ * why, unless nothing was requested in the first place.
+ */
+export interface DesignTimeResolution<T> {
+    /** The package-provided contribution, when one was found and loaded. */
+    contribution?: T;
+
+    /** The package that provided it. */
+    package?: string;
+
+    /** The host-provided editor kind used instead, for property editors the host implements itself. */
+    hostKind?: string;
+
+    /** Why the generic fallback is used. Absent when the request was satisfied or nothing was requested. */
+    diagnostic?: string;
+}

package/packages/PackageHostConfiguration.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { DialogTemplate, Layout, ScreenTemplate, Theme, UiProfile } from '@cratis/scene.model';
-import { resolvePackageDependencies } from '@cratis/scene.engine';
+import { TemplateCatalogEntry, describeTemplateCatalog, resolvePackageDependencies } from '@cratis/scene.engine';
 import { IconAdapterRegistry, createIconAdapterRegistry } from '../icons/IconAdapterRegistry';
 import { ScenePackageBundle, mergePackageRegistries, validatePackageBundle } from './ScenePackageBundle';
 
@@ -18,6 +18,9 @@ export interface PackageHostConfiguration {
     bundles: ScenePackageBundle[];
     profile: UiProfile;
     policy: PackageHostPolicy;
+
+    /** The Scene version the host runs, checked against each template's compatibility range when given. */
+    sceneVersion?: string;
 }
 
 export interface ResolvedPackageHost {
@@ -27,6 +30,12 @@ export interface ResolvedPackageHost {
     screenTemplates: ScreenTemplate[];
     dialogTemplates: DialogTemplate[];
     themes: Theme[];
+
+    /**
+     * Every template the approved packages provide, with compatibility, attribution and license metadata and
+     * whether it can be used with this package set. Template browsers read this rather than the raw lists.
+     */
+    templates: TemplateCatalogEntry[];
     icons: IconAdapterRegistry;
     assets: string[];
     fonts: string[];
@@ -100,6 +109,7 @@ export function resolvePackageHost(configuration: PackageHostConfiguration): Res
         screenTemplates: approved.flatMap(bundle => bundle.screenTemplates ?? []),
         dialogTemplates: approved.flatMap(bundle => bundle.dialogTemplates ?? []),
         themes: approved.flatMap(bundle => bundle.themes ?? []),
+        templates: describeTemplateCatalog(approved, configuration.sceneVersion),
         icons: createIconAdapterRegistry(approved.map(bundle => bundle.iconLibrary?.adapter).filter(adapter => adapter !== undefined)),
         assets: approvedAssets,
         fonts: approvedAssets.filter(isFontAsset),

package/packages/index.ts

@@ -2,18 +2,26 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 export * from './DesignTimeAction';
+export * from './DesignTimeActionOutcome';
+export * from './DesignTimeActionState';
 export * from './DesignTimeBundle';
 export * from './DesignTimeComponentProps';
 export * from './DesignTimeContext';
+export * from './DesignTimeContractVersion';
+export * from './DesignTimeExtensionPoint';
 export * from './DesignTimePropertyDisplayProps';
 export * from './DesignTimePropertyEditorProps';
 export * from './DesignTimeProvider';
+export * from './DesignTimeResolution';
 export * from '../navigation';
 export * from './EmbeddedPackageHost';
+export * from './loadDesignTimeContributions';
 export * from './PackageHostAssets';
 export * from './PackageHostConfiguration';
 export * from './PackageHostRenderMode';
 export * from './PackageHostView';
+export * from './resolveDesignTimeHost';
+export * from './runDesignTimeAction';
 export * from './ScenePackageBundle';
 export * from './StandalonePackageHost';
 export * from './WebViewPackageHost';

package/packages/loadDesignTimeContributions.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DesignTimeBundle } from './DesignTimeBundle';
+import { DesignTimeContractVersion } from './DesignTimeContractVersion';
+import { DesignTimeExtensionPoint, designTimeExtensionPointLabels } from './DesignTimeExtensionPoint';
+import { ScenePackageBundle } from './ScenePackageBundle';
+
+/**
+ * A package's design-time contributions as a host loaded them: only what the manifest declares, or nothing
+ * with the reason when the package cannot be loaded at all.
+ */
+export interface LoadedDesignTimeContributions {
+    contributions: Partial<Record<DesignTimeExtensionPoint, Record<string, unknown>>>;
+    unavailableReason?: string;
+}
+
+/**
+ * Loads the design-time contributions of approved bundles, checking each against the contract version this
+ * host implements and against what its manifest declares. Nothing is partially trusted: a package with an
+ * incompatible or unreadable contract version, or contributions its manifest does not declare at all,
+ * contributes nothing; a single undeclared contribution is left out; a declared one the bundle lacks is
+ * reported and falls back.
+ */
+export function loadDesignTimeContributions(
+    bundles: ScenePackageBundle[],
+    loadDesignTime: boolean,
+): { packages: Map<string, LoadedDesignTimeContributions>; diagnostics: string[] } {
+    const packages = new Map<string, LoadedDesignTimeContributions>();
+    const diagnostics: string[] = [];
+    const hostMajor = DesignTimeContractVersion.split('.')[0];
+
+    for (const { manifest, designTime } of bundles) {
+        const declared = manifest.designTime;
+        const unavailable = (reason: string) => {
+            diagnostics.push(reason);
+            packages.set(manifest.name, { contributions: {}, unavailableReason: reason });
+        };
+
+        if (!declared && !designTime) continue;
+        if (!loadDesignTime) {
+            packages.set(manifest.name, { contributions: {}, unavailableReason: `This host does not load design-time contributions, so package '${manifest.name}' uses generic editors` });
+            continue;
+        }
+
+        if (!declared) {
+            unavailable(`Package '${manifest.name}' provides design-time contributions its manifest does not declare; none are loaded`);
+            continue;
+        }
+
+        const version = declared.contractVersion ?? '1.0';
+        if (!/^\d+\.\d+$/.test(version)) {
+            unavailable(`Package '${manifest.name}' declares design-time contract version '${version}', which is not a major.minor version; none of its contributions are loaded`);
+            continue;
+        }
+
+        if (version.split('.')[0] !== hostMajor) {
+            unavailable(`Package '${manifest.name}' targets design-time contract ${version}, but this host implements ${DesignTimeContractVersion}; none of its contributions are loaded`);
+            continue;
+        }
+
+        packages.set(manifest.name, { contributions: declaredContributions(manifest.name, declared, designTime, diagnostics) });
+    }
+
+    return { packages, diagnostics };
+}
+
+function declaredContributions(
+    packageName: string,
+    declared: Record<DesignTimeExtensionPoint, string[]>,
+    provided: DesignTimeBundle | undefined,
+    diagnostics: string[],
+): LoadedDesignTimeContributions['contributions'] {
+    const contributions: LoadedDesignTimeContributions['contributions'] = {};
+
+    for (const point of Object.values(DesignTimeExtensionPoint)) {
+        const label = designTimeExtensionPointLabels[point];
+        const names = new Set(declared[point] ?? []);
+        const available = (provided?.[point] ?? {}) as Record<string, unknown>;
+        const loaded: Record<string, unknown> = {};
+
+        for (const name of names) {
+            if (name in available) {
+                loaded[name] = available[name];
+            } else {
+                diagnostics.push(`Package '${packageName}' declares the ${label} '${name}', but its design-time bundle does not provide it`);
+            }
+        }
+
+        for (const name of Object.keys(available).filter(name => !names.has(name))) {
+            diagnostics.push(`Package '${packageName}' provides the ${label} '${name}', which its manifest does not declare; it is not loaded`);
+        }
+
+        contributions[point] = loaded;
+    }
+
+    return contributions;
+}

package/packages/resolveDesignTimeHost.ts

@@ -0,0 +1,133 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ComponentType } from 'react';
+import { ComponentDescriptor, PropertyDescriptor } from '@cratis/scene.model';
+import { DesignTimeAction, DesignTimeActionContext } from './DesignTimeAction';
+import { DesignTimeActionOutcome } from './DesignTimeActionOutcome';
+import { DesignTimeActionState } from './DesignTimeActionState';
+import { DesignTimeComponentProps } from './DesignTimeComponentProps';
+import { DesignTimeExtensionPoint, designTimeExtensionPointLabels } from './DesignTimeExtensionPoint';
+import { DesignTimePropertyDisplayProps } from './DesignTimePropertyDisplayProps';
+import { DesignTimePropertyEditorProps } from './DesignTimePropertyEditorProps';
+import { DesignTimeResolution } from './DesignTimeResolution';
+import { LoadedDesignTimeContributions, loadDesignTimeContributions } from './loadDesignTimeContributions';
+import { PackageHostConfiguration, ResolvedPackageHost, resolvePackageHost } from './PackageHostConfiguration';
+import { runDesignTimeAction } from './runDesignTimeAction';
+
+/**
+ * The generic design-time host contract: every package - first or third party - is reached through these
+ * lookups, so a designer never switches on package or component names.
+ */
+export interface DesignTimeHost {
+    /** The runtime package host the design-time contributions were loaded alongside. */
+    host: ResolvedPackageHost;
+
+    /** Package-level problems: the host's own, contract version mismatches and declared/provided disagreements. */
+    diagnostics: string[];
+
+    preview(descriptor: ComponentDescriptor): DesignTimeResolution<ComponentType<DesignTimeComponentProps>>;
+    designer(descriptor: ComponentDescriptor): DesignTimeResolution<ComponentType<DesignTimeComponentProps>>;
+    propertyEditor(descriptor: ComponentDescriptor, property: PropertyDescriptor): DesignTimeResolution<ComponentType<DesignTimePropertyEditorProps>>;
+    propertyDisplay(descriptor: ComponentDescriptor): DesignTimeResolution<ComponentType<DesignTimePropertyDisplayProps>>;
+
+    /** The component's actions, with the visibility and enablement their owning package decides. */
+    actions(descriptor: ComponentDescriptor, context: DesignTimeActionContext): DesignTimeActionState[];
+
+    /** Runs an action and submits its canonical edit batch to the host through `context.submitAction`. */
+    runAction(descriptor: ComponentDescriptor, actionId: string, context: DesignTimeActionContext): DesignTimeActionOutcome;
+
+    /** Every unknown or unavailable extension the approved packages' descriptors ask for. */
+    diagnoseDescriptors(): string[];
+}
+
+/** Options for {@link resolveDesignTimeHost}. */
+export interface DesignTimeHostOptions {
+    /** Property editor kinds the host implements itself, such as an icon picker or a query binder. */
+    hostEditorKinds?: string[];
+}
+
+/**
+ * Resolves a package host and the design-time contributions of its approved packages. Design-time code is
+ * only loaded when the host policy sets `loadDesignTime`; a runtime host gets generic fallbacks everywhere.
+ */
+export function resolveDesignTimeHost(configuration: PackageHostConfiguration, options: DesignTimeHostOptions = {}): DesignTimeHost {
+    const host = resolvePackageHost(configuration);
+    const loaded = loadDesignTimeContributions(host.bundles, configuration.policy.loadDesignTime === true);
+    const hostEditorKinds = new Set(options.hostEditorKinds ?? []);
+    const approved = new Set(host.bundles.map(bundle => bundle.manifest.name));
+
+    const lookup = <T>(descriptor: ComponentDescriptor, point: DesignTimeExtensionPoint, kind: string | undefined): DesignTimeResolution<T> => {
+        if (!kind) return {};
+        const label = designTimeExtensionPointLabels[point];
+        const separator = kind.indexOf(':');
+        const owner = separator > 0 ? kind.substring(0, separator) : ownerOf(descriptor);
+        const name = separator > 0 ? kind.substring(separator + 1) : kind;
+        const outcome = point === DesignTimeExtensionPoint.Action ? 'the host shows it disabled' : `the host uses its generic ${label}`;
+        const fallback = (reason: string) => ({ diagnostic: `'${descriptor.component}' asks for the ${label} '${kind}', ${reason}; ${outcome}` });
+
+        if (!approved.has(owner)) return fallback(`but package '${owner}' is not approved by this host`);
+        const contributions: LoadedDesignTimeContributions | undefined = loaded.packages.get(owner);
+        if (contributions?.unavailableReason) return fallback(`but design-time contributions from package '${owner}' are not loaded`);
+        const contribution = contributions?.contributions[point]?.[name] as T | undefined;
+        if (contribution !== undefined) return { contribution, package: owner };
+        if (point === DesignTimeExtensionPoint.PropertyEditor && separator < 0 && hostEditorKinds.has(kind)) return { hostKind: kind };
+        return fallback(`which package '${owner}' does not provide`);
+    };
+
+    const actionOf = (descriptor: ComponentDescriptor, actionId: string): DesignTimeAction | undefined =>
+        loaded.packages.get(ownerOf(descriptor))?.contributions[DesignTimeExtensionPoint.Action]?.[actionId] as DesignTimeAction | undefined;
+
+    const actions = (descriptor: ComponentDescriptor, context: DesignTimeActionContext): DesignTimeActionState[] =>
+        (descriptor.actions ?? []).map(action => {
+            const state = { descriptor: action, package: ownerOf(descriptor) };
+            const handler = actionOf(descriptor, action.id);
+            if (!handler) {
+                const resolution = lookup<DesignTimeAction>(descriptor, DesignTimeExtensionPoint.Action, action.id);
+                return { ...state, visible: true, enabled: false, diagnostic: resolution.diagnostic };
+            }
+
+            try {
+                return { ...state, visible: handler.isVisible(context), enabled: handler.isEnabled(context) };
+            } catch (error) {
+                return { ...state, visible: true, enabled: false, diagnostic: `Action '${action.id}' could not decide its availability: ${String(error)}` };
+            }
+        });
+
+    const descriptors = host.bundles.flatMap(bundle => bundle.descriptors ?? []);
+
+    return {
+        host,
+        diagnostics: [...host.diagnostics, ...loaded.diagnostics],
+        preview: descriptor => lookup(descriptor, DesignTimeExtensionPoint.Preview, descriptor.previewKind),
+        designer: descriptor => lookup(descriptor, DesignTimeExtensionPoint.Designer, descriptor.editorKind),
+        propertyEditor: (descriptor, property) => lookup(descriptor, DesignTimeExtensionPoint.PropertyEditor, property.editorKind),
+        propertyDisplay: descriptor => lookup(descriptor, DesignTimeExtensionPoint.PropertyDisplay, descriptor.propertyDisplayKind),
+        actions,
+        runAction: (descriptor, actionId, context) => {
+            const state = actions(descriptor, context).find(action => action.descriptor.id === actionId);
+            const handler = actionOf(descriptor, actionId);
+            if (!state || !handler || !state.visible || !state.enabled) {
+                const reason = state?.diagnostic ?? (state ? `Action '${actionId}' is not available here` : `'${descriptor.component}' has no action '${actionId}'`);
+                return { submitted: false, edits: [], diagnostics: [reason] };
+            }
+
+            return runDesignTimeAction(handler, context);
+        },
+        diagnoseDescriptors: () =>
+            descriptors.flatMap(descriptor => [
+                lookup(descriptor, DesignTimeExtensionPoint.Preview, descriptor.previewKind),
+                lookup(descriptor, DesignTimeExtensionPoint.Designer, descriptor.editorKind),
+                lookup(descriptor, DesignTimeExtensionPoint.PropertyDisplay, descriptor.propertyDisplayKind),
+                ...descriptor.properties.map(property => lookup(descriptor, DesignTimeExtensionPoint.PropertyEditor, property.editorKind)),
+                ...(descriptor.actions ?? []).map(action => lookup(descriptor, DesignTimeExtensionPoint.Action, action.id)),
+            ])
+                .map(resolution => resolution.diagnostic)
+                .filter((diagnostic): diagnostic is string => diagnostic !== undefined),
+    };
+}
+
+function ownerOf(descriptor: ComponentDescriptor): string {
+    const separator = descriptor.component.indexOf(':');
+    return separator > 0 ? descriptor.component.substring(0, separator) : descriptor.component;
+}

package/packages/runDesignTimeAction.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneEdit, SceneEditKind } from '@cratis/scene.model';
+import { DesignTimeAction, DesignTimeActionContext } from './DesignTimeAction';
+import { DesignTimeActionOutcome } from './DesignTimeActionOutcome';
+
+const editKinds = new Set<string>(Object.values(SceneEditKind));
+
+/**
+ * Runs one design-time action and hands its edit batch to the host as a single canonical batch, so the host's
+ * own validation and undo/redo stay authoritative. A batch containing anything that is not a canonical Scene
+ * edit is rejected whole - a partially applied action is never reported as success.
+ */
+export function runDesignTimeAction(action: DesignTimeAction, context: DesignTimeActionContext): DesignTimeActionOutcome {
+    let result: { edits: SceneEdit[]; diagnostics: string[] };
+    try {
+        result = action.execute(context);
+    } catch (error) {
+        return { submitted: false, edits: [], diagnostics: [`Action '${action.descriptor.id}' failed: ${String(error)}`] };
+    }
+
+    const invalid = result.edits.filter(edit => !editKinds.has((edit as { kind?: string }).kind ?? ''));
+    if (invalid.length > 0) {
+        return {
+            submitted: false,
+            edits: result.edits,
+            diagnostics: [...result.diagnostics, `Action '${action.descriptor.id}' produced ${invalid.length} edit(s) that are not canonical Scene edits; nothing was submitted`],
+        };
+    }
+
+    if (result.edits.length === 0) return { submitted: false, edits: [], diagnostics: result.diagnostics };
+
+    context.submitAction(action.descriptor.id, result.edits);
+    return { submitted: true, edits: result.edits, diagnostics: result.diagnostics };
+}