@cratis/scene.engine 4.7.0 → 4.9.0

package/dist/esm/validateBindingExpression.d.ts

@@ -0,0 +1,8 @@
+import { BindingExpression } from '@cratis/scene.model';
+import { BindingDiagnostic } from './BindingDiagnostic';
+import { BindingScope } from './BindingScope';
+export declare function validateBindingExpression(binding: BindingExpression, scope: BindingScope, options?: {
+    targetElementId?: string;
+    resolvingElementIds?: string[];
+}): BindingDiagnostic[];
+//# sourceMappingURL=validateBindingExpression.d.ts.map

package/dist/esm/validateBindingExpression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateBindingExpression.d.ts","sourceRoot":"","sources":["../../validateBindingExpression.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAqD,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM9C,wBAAgB,yBAAyB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAA;CAAO,GAC3E,iBAAiB,EAAE,CAoCrB"}

package/dist/esm/validateBindingExpression.js

@@ -0,0 +1,68 @@
+import { BindingSourceKind, BindingMode, PropertyValueType } from '@cratis/scene.model';
+import { resolveBindingExpression } from './resolveBindingExpression.js';
+
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Validates one binding against available runtime scope and optional component dependency stack.
+ */ function validateBindingExpression(binding, scope, options = {}) {
+    const diagnostics = [];
+    const kind = binding.kind ?? BindingSourceKind.DataContext;
+    if (kind === BindingSourceKind.QueryResult && !binding.query) {
+        diagnostics.push(problem('missingQuery', 'Query result bindings must name the query they read from.', 'query'));
+    }
+    if (kind === BindingSourceKind.ComponentProperty) {
+        if (!binding.componentId) {
+            diagnostics.push(problem('missingComponent', 'Component property bindings must name the source component id.', 'componentId'));
+        } else if (!scope.componentOutputs?.[binding.componentId]) {
+            diagnostics.push(problem('unknownComponent', `No component output scope exists for '${binding.componentId}'.`, 'componentId'));
+        }
+        if (binding.componentId && options.targetElementId === binding.componentId) {
+            diagnostics.push(problem('bindingCycle', `Component '${binding.componentId}' cannot bind to its own output.`, 'componentId'));
+        }
+        if (binding.componentId && options.resolvingElementIds?.includes(binding.componentId)) {
+            diagnostics.push(problem('bindingCycle', `Binding to '${binding.componentId}' would create a component binding cycle.`, 'componentId'));
+        }
+    }
+    if (binding.mode === BindingMode.TwoWay && kind !== BindingSourceKind.ComponentProperty) {
+        diagnostics.push(problem('unsupportedTwoWayBinding', 'Two-way bindings require a component output source.', 'mode'));
+    }
+    if (binding.expectedValueType !== undefined) {
+        const value = resolveBindingExpression(binding, scope);
+        if (!matchesExpectedType(value, binding.expectedValueType)) {
+            diagnostics.push(problem('bindingTypeMismatch', `Binding value does not match expected ${binding.expectedValueType}.`, 'expectedValueType'));
+        }
+    }
+    return diagnostics;
+}
+function problem(code, message, path) {
+    return {
+        code,
+        message,
+        path
+    };
+}
+function matchesExpectedType(value, type) {
+    if (value === null || value === undefined) return true;
+    switch(type){
+        case PropertyValueType.String:
+        case PropertyValueType.Enum:
+        case PropertyValueType.Icon:
+        case PropertyValueType.Destination:
+        case PropertyValueType.QueryReference:
+            return typeof value === 'string' || typeof value === 'object' && !Array.isArray(value);
+        case PropertyValueType.Number:
+            return typeof value === 'number' && !Number.isNaN(value);
+        case PropertyValueType.Boolean:
+            return typeof value === 'boolean';
+        case PropertyValueType.Collection:
+            return Array.isArray(value);
+        case PropertyValueType.Object:
+            return typeof value === 'object' && !Array.isArray(value);
+        case PropertyValueType.Json:
+            return true;
+    }
+}
+
+export { validateBindingExpression };
+//# sourceMappingURL=validateBindingExpression.js.map

package/dist/esm/validateBindingExpression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateBindingExpression.js","sources":["../../validateBindingExpression.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { BindingExpression, BindingMode, BindingSourceKind, PropertyValueType } from '@cratis/scene.model';\nimport { BindingDiagnostic } from './BindingDiagnostic';\nimport { BindingScope } from './BindingScope';\nimport { resolveBindingExpression } from './resolveBindingExpression';\n\n/**\n * Validates one binding against available runtime scope and optional component dependency stack.\n */\nexport function validateBindingExpression(\n    binding: BindingExpression,\n    scope: BindingScope,\n    options: { targetElementId?: string; resolvingElementIds?: string[] } = {},\n): BindingDiagnostic[] {\n    const diagnostics: BindingDiagnostic[] = [];\n    const kind = binding.kind ?? BindingSourceKind.DataContext;\n\n    if (kind === BindingSourceKind.QueryResult && !binding.query) {\n        diagnostics.push(problem('missingQuery', 'Query result bindings must name the query they read from.', 'query'));\n    }\n\n    if (kind === BindingSourceKind.ComponentProperty) {\n        if (!binding.componentId) {\n            diagnostics.push(problem('missingComponent', 'Component property bindings must name the source component id.', 'componentId'));\n        } else if (!scope.componentOutputs?.[binding.componentId]) {\n            diagnostics.push(problem('unknownComponent', `No component output scope exists for '${binding.componentId}'.`, 'componentId'));\n        }\n\n        if (binding.componentId && options.targetElementId === binding.componentId) {\n            diagnostics.push(problem('bindingCycle', `Component '${binding.componentId}' cannot bind to its own output.`, 'componentId'));\n        }\n\n        if (binding.componentId && options.resolvingElementIds?.includes(binding.componentId)) {\n            diagnostics.push(problem('bindingCycle', `Binding to '${binding.componentId}' would create a component binding cycle.`, 'componentId'));\n        }\n    }\n\n    if (binding.mode === BindingMode.TwoWay && kind !== BindingSourceKind.ComponentProperty) {\n        diagnostics.push(problem('unsupportedTwoWayBinding', 'Two-way bindings require a component output source.', 'mode'));\n    }\n\n    if (binding.expectedValueType !== undefined) {\n        const value = resolveBindingExpression(binding, scope);\n        if (!matchesExpectedType(value, binding.expectedValueType)) {\n            diagnostics.push(problem('bindingTypeMismatch', `Binding value does not match expected ${binding.expectedValueType}.`, 'expectedValueType'));\n        }\n    }\n\n    return diagnostics;\n}\n\nfunction problem(code: string, message: string, path?: string): BindingDiagnostic {\n    return { code, message, path };\n}\n\nfunction matchesExpectedType(value: unknown, type: PropertyValueType): boolean {\n    if (value === null || value === undefined) return true;\n    switch (type) {\n        case PropertyValueType.String:\n        case PropertyValueType.Enum:\n        case PropertyValueType.Icon:\n        case PropertyValueType.Destination:\n        case PropertyValueType.QueryReference:\n            return typeof value === 'string' || (typeof value === 'object' && !Array.isArray(value));\n        case PropertyValueType.Number:\n            return typeof value === 'number' && !Number.isNaN(value);\n        case PropertyValueType.Boolean:\n            return typeof value === 'boolean';\n        case PropertyValueType.Collection:\n            return Array.isArray(value);\n        case PropertyValueType.Object:\n            return typeof value === 'object' && !Array.isArray(value);\n        case PropertyValueType.Json:\n            return true;\n    }\n}\n"],"names":["validateBindingExpression","binding","scope","options","diagnostics","kind","BindingSourceKind","DataContext","QueryResult","query","push","problem","ComponentProperty","componentId","componentOutputs","targetElementId","resolvingElementIds","includes","mode","BindingMode","TwoWay","expectedValueType","undefined","value","resolveBindingExpression","matchesExpectedType","code","message","path","type","PropertyValueType","String","Enum","Icon","Destination","QueryReference","Array","isArray","Number","isNaN","Boolean","Collection","Object","Json"],"mappings":"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"}

package/dist/esm/validateNavigationDestinations.d.ts

@@ -0,0 +1,10 @@
+import { DestinationReference, Layout, ScreenTemplate } from '@cratis/scene.model';
+export interface NavigationDestinationDiagnostic {
+    code: string;
+    message: string;
+}
+export declare function validateNavigationDestinations(destinations: DestinationReference[], surfaces?: {
+    layouts?: Layout[];
+    screenTemplates?: ScreenTemplate[];
+}): NavigationDestinationDiagnostic[];
+//# sourceMappingURL=validateNavigationDestinations.d.ts.map

package/dist/esm/validateNavigationDestinations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateNavigationDestinations.d.ts","sourceRoot":"","sources":["../../validateNavigationDestinations.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEnF,MAAM,WAAW,+BAA+B;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACnB;AAKD,wBAAgB,8BAA8B,CAC1C,YAAY,EAAE,oBAAoB,EAAE,EACpC,QAAQ,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAA;CAAO,GAC1E,+BAA+B,EAAE,CA0BnC"}

package/dist/esm/validateNavigationDestinations.js

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/**
+ * Validates destinations against the outlet/route declarations owned by layouts and templates.
+ */ function validateNavigationDestinations(destinations, surfaces = {}) {
+    const diagnostics = [];
+    const outlets = new Set();
+    const routes = new Set();
+    for (const surface of [
+        ...surfaces.layouts ?? [],
+        ...surfaces.screenTemplates ?? []
+    ]){
+        for (const outlet of surface.outlets ?? []){
+            if (outlets.has(outlet.name)) diagnostics.push({
+                code: 'duplicateOutlet',
+                message: `Outlet '${outlet.name}' is declared more than once.`
+            });
+            outlets.add(outlet.name);
+        }
+    }
+    for (const destination of destinations){
+        if (destination.outlet && !outlets.has(destination.outlet)) {
+            diagnostics.push({
+                code: 'missingOutlet',
+                message: `Destination targets missing outlet '${destination.outlet}'.`
+            });
+        }
+        if (destination.route) {
+            if (routes.has(destination.route)) diagnostics.push({
+                code: 'duplicateRoute',
+                message: `Route '${destination.route}' is used by more than one destination.`
+            });
+            routes.add(destination.route);
+        }
+        if (!destination.screen && !destination.module && !destination.route && !destination.dialog) {
+            diagnostics.push({
+                code: 'unavailableTarget',
+                message: 'Destination must name a screen, stable identity, route or dialog.'
+            });
+        }
+    }
+    return diagnostics;
+}
+
+export { validateNavigationDestinations };
+//# sourceMappingURL=validateNavigationDestinations.js.map

package/dist/esm/validateNavigationDestinations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateNavigationDestinations.js","sources":["../../validateNavigationDestinations.ts"],"sourcesContent":["// Copyright (c) Cratis. All rights reserved.\n// Licensed under the MIT license. See LICENSE file in the project root for full license information.\n\nimport { DestinationReference, Layout, ScreenTemplate } from '@cratis/scene.model';\n\nexport interface NavigationDestinationDiagnostic {\n    code: string;\n    message: string;\n}\n\n/**\n * Validates destinations against the outlet/route declarations owned by layouts and templates.\n */\nexport function validateNavigationDestinations(\n    destinations: DestinationReference[],\n    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[] } = {},\n): NavigationDestinationDiagnostic[] {\n    const diagnostics: NavigationDestinationDiagnostic[] = [];\n    const outlets = new Set<string>();\n    const routes = new Set<string>();\n\n    for (const surface of [...(surfaces.layouts ?? []), ...(surfaces.screenTemplates ?? [])]) {\n        for (const outlet of surface.outlets ?? []) {\n            if (outlets.has(outlet.name)) diagnostics.push({ code: 'duplicateOutlet', message: `Outlet '${outlet.name}' is declared more than once.` });\n            outlets.add(outlet.name);\n        }\n    }\n\n    for (const destination of destinations) {\n        if (destination.outlet && !outlets.has(destination.outlet)) {\n            diagnostics.push({ code: 'missingOutlet', message: `Destination targets missing outlet '${destination.outlet}'.` });\n        }\n        if (destination.route) {\n            if (routes.has(destination.route)) diagnostics.push({ code: 'duplicateRoute', message: `Route '${destination.route}' is used by more than one destination.` });\n            routes.add(destination.route);\n        }\n        if (!destination.screen && !destination.module && !destination.route && !destination.dialog) {\n            diagnostics.push({ code: 'unavailableTarget', message: 'Destination must name a screen, stable identity, route or dialog.' });\n        }\n    }\n\n    return diagnostics;\n}\n"],"names":["validateNavigationDestinations","destinations","surfaces","diagnostics","outlets","Set","routes","surface","layouts","screenTemplates","outlet","has","name","push","code","message","add","destination","route","screen","module","dialog"],"mappings":"AAAA;AACA;AASA;;AAEC,IACM,SAASA,8BAAAA,CACZC,YAAoC,EACpCC,QAAAA,GAAuE,EAAE,EAAA;AAEzE,IAAA,MAAMC,cAAiD,EAAE;AACzD,IAAA,MAAMC,UAAU,IAAIC,GAAAA,EAAAA;AACpB,IAAA,MAAMC,SAAS,IAAID,GAAAA,EAAAA;AAEnB,IAAA,KAAK,MAAME,OAAAA,IAAW;WAAKL,QAAAA,CAASM,OAAO,IAAI,EAAE;WAAON,QAAAA,CAASO,eAAe,IAAI;KAAI,CAAE;AACtF,QAAA,KAAK,MAAMC,MAAAA,IAAUH,OAAAA,CAAQH,OAAO,IAAI,EAAE,CAAE;YACxC,IAAIA,OAAAA,CAAQO,GAAG,CAACD,MAAAA,CAAOE,IAAI,CAAA,EAAGT,WAAAA,CAAYU,IAAI,CAAC;gBAAEC,IAAAA,EAAM,iBAAA;AAAmBC,gBAAAA,OAAAA,EAAS,CAAC,QAAQ,EAAEL,OAAOE,IAAI,CAAC,6BAA6B;AAAE,aAAA,CAAA;YACzIR,OAAAA,CAAQY,GAAG,CAACN,MAAAA,CAAOE,IAAI,CAAA;AAC3B,QAAA;AACJ,IAAA;IAEA,KAAK,MAAMK,eAAehB,YAAAA,CAAc;QACpC,IAAIgB,WAAAA,CAAYP,MAAM,IAAI,CAACN,QAAQO,GAAG,CAACM,WAAAA,CAAYP,MAAM,CAAA,EAAG;AACxDP,YAAAA,WAAAA,CAAYU,IAAI,CAAC;gBAAEC,IAAAA,EAAM,eAAA;AAAiBC,gBAAAA,OAAAA,EAAS,CAAC,oCAAoC,EAAEE,YAAYP,MAAM,CAAC,EAAE;AAAE,aAAA,CAAA;AACrH,QAAA;QACA,IAAIO,WAAAA,CAAYC,KAAK,EAAE;YACnB,IAAIZ,MAAAA,CAAOK,GAAG,CAACM,WAAAA,CAAYC,KAAK,CAAA,EAAGf,WAAAA,CAAYU,IAAI,CAAC;gBAAEC,IAAAA,EAAM,gBAAA;AAAkBC,gBAAAA,OAAAA,EAAS,CAAC,OAAO,EAAEE,YAAYC,KAAK,CAAC,uCAAuC;AAAE,aAAA,CAAA;YAC5JZ,MAAAA,CAAOU,GAAG,CAACC,WAAAA,CAAYC,KAAK,CAAA;AAChC,QAAA;AACA,QAAA,IAAI,CAACD,WAAAA,CAAYE,MAAM,IAAI,CAACF,WAAAA,CAAYG,MAAM,IAAI,CAACH,YAAYC,KAAK,IAAI,CAACD,WAAAA,CAAYI,MAAM,EAAE;AACzFlB,YAAAA,WAAAA,CAAYU,IAAI,CAAC;gBAAEC,IAAAA,EAAM,mBAAA;gBAAqBC,OAAAA,EAAS;AAAoE,aAAA,CAAA;AAC/H,QAAA;AACJ,IAAA;IAEA,OAAOZ,WAAAA;AACX;;"}

package/index.ts

@@ -3,6 +3,10 @@
 
 export * from './Renderer';
 export * from './BindingResolver';
+export * from './BindingScope';
+export * from './BindingDiagnostic';
+export * from './resolveBindingExpression';
+export * from './validateBindingExpression';
 export * from './renderElement';
 export * from './elementKind';
 export * from './panelKind';
@@ -21,10 +25,12 @@ export * from './packageVersionRange';
 export * from './resolvePackageDependencies';
 export * from './packageCatalog';
 export * from './resolveScreenTemplates';
+export * from './templateApplicability';
 export * from './buildStarterProfile';
 export * from './incompatibleStarterThemes';
 export * from './ActionDispatcher';
 export * from './runActions';
 export * from './resolveBehaviors';
 export * from './resolveStrings';
+export * from './validateNavigationDestinations';
 export * from './editing';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.7.0",
+    "version": "4.9.0",
     "description": "The Scene runtime: walks a Scene element tree and drives whichever renderer is plugged in. Does not know React, or any other rendering platform, exists.",
     "keywords": [
         "cratis",
@@ -48,9 +48,9 @@
         "up": "yarn g:up"
     },
     "dependencies": {
-        "@cratis/scene.model": "4.7.0"
+        "@cratis/scene.model": "4.9.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.7.0"
+        "@cratis/scene.model": "4.9.0"
     }
 }

package/resolveBindingExpression.ts

@@ -0,0 +1,55 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression, BindingNullBehavior, BindingSourceKind } from '@cratis/scene.model';
+import { BindingScope } from './BindingScope';
+
+/**
+ * Resolves a typed binding against the shared runtime binding scope.
+ */
+export function resolveBindingExpression(binding: BindingExpression, scope: BindingScope): unknown {
+    const kind = binding.kind ?? BindingSourceKind.DataContext;
+    if (kind === BindingSourceKind.Literal) return binding.value;
+
+    const source = sourceValue(binding, scope, kind);
+    const value = readPath(source, sourcePath(binding, kind));
+    if (value !== null && value !== undefined) return value;
+
+    if (binding.nullBehavior === BindingNullBehavior.Preserve) return undefined;
+    if (binding.nullBehavior === BindingNullBehavior.Clear) return null;
+    return value;
+}
+
+/**
+ * Creates a legacy resolver function from a binding scope.
+ */
+export function createBindingResolver(scope: BindingScope): (binding: BindingExpression) => unknown {
+    return binding => resolveBindingExpression(binding, scope);
+}
+
+function sourceValue(binding: BindingExpression, scope: BindingScope, kind: BindingSourceKind): unknown {
+    switch (kind) {
+        case BindingSourceKind.DataContext:
+            return scope.dataContext;
+        case BindingSourceKind.QueryResult:
+            return binding.query ? scope.queryResults?.[binding.query] : undefined;
+        case BindingSourceKind.ComponentProperty:
+            return binding.componentId ? scope.componentOutputs?.[binding.componentId] : undefined;
+        case BindingSourceKind.Literal:
+            return binding.value;
+    }
+}
+
+function sourcePath(binding: BindingExpression, kind: BindingSourceKind): string {
+    if (kind === BindingSourceKind.ComponentProperty) return binding.componentPropertyPath ?? binding.path;
+    return binding.path;
+}
+
+function readPath(source: unknown, path: string): unknown {
+    if (!path) return source;
+    return path.split('.').reduce<unknown>((current, segment) => {
+        if (current === null || current === undefined) return undefined;
+        if (typeof current !== 'object') return undefined;
+        return (current as Record<string, unknown>)[segment];
+    }, source);
+}

package/templateApplicability.ts

@@ -0,0 +1,75 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DialogTemplate, Layout, ScreenTemplate, TemplateMetadata, TemplateScope } from '@cratis/scene.model';
+
+type TemplateKind = 'Layout' | 'ScreenTemplate' | 'DialogTemplate';
+type TemplateContainer = Pick<Layout, 'name' | 'slots'>;
+
+/** Validates application-shell selection without introducing a competing shell model. */
+export function validateLayoutApplicability(layout: Layout | undefined, scope: TemplateScope): string[] {
+    return layout ? validateRole(layout.name, 'Layout', layout.metadata, scope) : [];
+}
+
+/**
+ * Validates selection at any depth of the application hierarchy, including qualified fitsSlot names.
+ * Undefined represents outlet-only composition and is valid. Invalid author input is never rewritten.
+ */
+export function validateScreenTemplateApplicability(
+    template: ScreenTemplate | undefined,
+    scope: TemplateScope,
+    container?: TemplateContainer,
+): string[] {
+    if (!template) return [];
+    const problems = validateRole(template.name, 'ScreenTemplate', template.metadata, scope);
+    if (template.fitsSlot !== undefined) {
+        const separator = template.fitsSlot.lastIndexOf('.');
+        const qualifier = separator < 0 ? undefined : template.fitsSlot.slice(0, separator);
+        const slot = separator < 0 ? template.fitsSlot : template.fitsSlot.slice(separator + 1);
+        if (!container || (qualifier !== undefined && qualifier !== container.name) || !container.slots.some(candidate => candidate.name === slot)) {
+            problems.push(`Template '${template.name}' does not fit slot '${template.fitsSlot}' on '${container?.name ?? '(no container)'}'`);
+        }
+    }
+    return problems;
+}
+
+/** Validates an overlay template separately from slot-based screen composition. */
+export function validateDialogTemplateApplicability(template: DialogTemplate | undefined, scope: TemplateScope): string[] {
+    return template ? validateRole(template.name, 'DialogTemplate', template.metadata, scope) : [];
+}
+
+/** The shared picker predicate uses exactly the same rules as validation on apply. */
+export function filterApplicableScreenTemplates(
+    templates: readonly ScreenTemplate[],
+    scope: TemplateScope,
+    container?: TemplateContainer,
+): ScreenTemplate[] {
+    return templates.filter(template => validateScreenTemplateApplicability(template, scope, container).length === 0);
+}
+
+function validateRole(name: string, kind: TemplateKind, metadata: TemplateMetadata | undefined, scope: TemplateScope): string[] {
+    const problems: string[] = [];
+    if (!Object.values(TemplateScope).includes(scope)) {
+        problems.push(`Template '${name}' has unknown target scope '${scope}'`);
+    } else if ((kind === 'Layout') !== (scope === TemplateScope.Application)) {
+        problems.push(`Template '${name}' of kind '${kind}' cannot be applied at scope '${scope}'`);
+    }
+    if (metadata?.type === 'ApplicationShell' && kind !== 'Layout') {
+        problems.push(`Template '${name}' of type 'ApplicationShell' must be a Layout`);
+    }
+    if (metadata?.type === 'Dialog' && kind !== 'DialogTemplate') {
+        problems.push(`Template '${name}' of type 'Dialog' must be a DialogTemplate`);
+    }
+    if (kind === 'Layout' && ['Workspace', 'List', 'Detail', 'Form'].includes(metadata?.type ?? '')) {
+        problems.push(`Template '${name}' of type '${metadata?.type}' must not be a Layout`);
+    }
+    for (const declaredScope of metadata?.scopes ?? []) {
+        if (!Object.values(TemplateScope).includes(declaredScope)) {
+            problems.push(`Template '${name}' declares unknown scope '${declaredScope}'`);
+        }
+    }
+    if (metadata?.scopes !== undefined && !metadata.scopes.includes(scope)) {
+        problems.push(`Template '${name}' does not declare scope '${scope}'`);
+    }
+    return problems;
+}

package/validateBindingExpression.ts

@@ -0,0 +1,78 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression, BindingMode, BindingSourceKind, PropertyValueType } from '@cratis/scene.model';
+import { BindingDiagnostic } from './BindingDiagnostic';
+import { BindingScope } from './BindingScope';
+import { resolveBindingExpression } from './resolveBindingExpression';
+
+/**
+ * Validates one binding against available runtime scope and optional component dependency stack.
+ */
+export function validateBindingExpression(
+    binding: BindingExpression,
+    scope: BindingScope,
+    options: { targetElementId?: string; resolvingElementIds?: string[] } = {},
+): BindingDiagnostic[] {
+    const diagnostics: BindingDiagnostic[] = [];
+    const kind = binding.kind ?? BindingSourceKind.DataContext;
+
+    if (kind === BindingSourceKind.QueryResult && !binding.query) {
+        diagnostics.push(problem('missingQuery', 'Query result bindings must name the query they read from.', 'query'));
+    }
+
+    if (kind === BindingSourceKind.ComponentProperty) {
+        if (!binding.componentId) {
+            diagnostics.push(problem('missingComponent', 'Component property bindings must name the source component id.', 'componentId'));
+        } else if (!scope.componentOutputs?.[binding.componentId]) {
+            diagnostics.push(problem('unknownComponent', `No component output scope exists for '${binding.componentId}'.`, 'componentId'));
+        }
+
+        if (binding.componentId && options.targetElementId === binding.componentId) {
+            diagnostics.push(problem('bindingCycle', `Component '${binding.componentId}' cannot bind to its own output.`, 'componentId'));
+        }
+
+        if (binding.componentId && options.resolvingElementIds?.includes(binding.componentId)) {
+            diagnostics.push(problem('bindingCycle', `Binding to '${binding.componentId}' would create a component binding cycle.`, 'componentId'));
+        }
+    }
+
+    if (binding.mode === BindingMode.TwoWay && kind !== BindingSourceKind.ComponentProperty) {
+        diagnostics.push(problem('unsupportedTwoWayBinding', 'Two-way bindings require a component output source.', 'mode'));
+    }
+
+    if (binding.expectedValueType !== undefined) {
+        const value = resolveBindingExpression(binding, scope);
+        if (!matchesExpectedType(value, binding.expectedValueType)) {
+            diagnostics.push(problem('bindingTypeMismatch', `Binding value does not match expected ${binding.expectedValueType}.`, 'expectedValueType'));
+        }
+    }
+
+    return diagnostics;
+}
+
+function problem(code: string, message: string, path?: string): BindingDiagnostic {
+    return { code, message, path };
+}
+
+function matchesExpectedType(value: unknown, type: PropertyValueType): boolean {
+    if (value === null || value === undefined) return true;
+    switch (type) {
+        case PropertyValueType.String:
+        case PropertyValueType.Enum:
+        case PropertyValueType.Icon:
+        case PropertyValueType.Destination:
+        case PropertyValueType.QueryReference:
+            return typeof value === 'string' || (typeof value === 'object' && !Array.isArray(value));
+        case PropertyValueType.Number:
+            return typeof value === 'number' && !Number.isNaN(value);
+        case PropertyValueType.Boolean:
+            return typeof value === 'boolean';
+        case PropertyValueType.Collection:
+            return Array.isArray(value);
+        case PropertyValueType.Object:
+            return typeof value === 'object' && !Array.isArray(value);
+        case PropertyValueType.Json:
+            return true;
+    }
+}

package/validateNavigationDestinations.ts

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationReference, Layout, ScreenTemplate } from '@cratis/scene.model';
+
+export interface NavigationDestinationDiagnostic {
+    code: string;
+    message: string;
+}
+
+/**
+ * Validates destinations against the outlet/route declarations owned by layouts and templates.
+ */
+export function validateNavigationDestinations(
+    destinations: DestinationReference[],
+    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[] } = {},
+): NavigationDestinationDiagnostic[] {
+    const diagnostics: NavigationDestinationDiagnostic[] = [];
+    const outlets = new Set<string>();
+    const routes = new Set<string>();
+
+    for (const surface of [...(surfaces.layouts ?? []), ...(surfaces.screenTemplates ?? [])]) {
+        for (const outlet of surface.outlets ?? []) {
+            if (outlets.has(outlet.name)) diagnostics.push({ code: 'duplicateOutlet', message: `Outlet '${outlet.name}' is declared more than once.` });
+            outlets.add(outlet.name);
+        }
+    }
+
+    for (const destination of destinations) {
+        if (destination.outlet && !outlets.has(destination.outlet)) {
+            diagnostics.push({ code: 'missingOutlet', message: `Destination targets missing outlet '${destination.outlet}'.` });
+        }
+        if (destination.route) {
+            if (routes.has(destination.route)) diagnostics.push({ code: 'duplicateRoute', message: `Route '${destination.route}' is used by more than one destination.` });
+            routes.add(destination.route);
+        }
+        if (!destination.screen && !destination.module && !destination.route && !destination.dialog) {
+            diagnostics.push({ code: 'unavailableTarget', message: 'Destination must name a screen, stable identity, route or dialog.' });
+        }
+    }
+
+    return diagnostics;
+}