@cratis/scene.engine 4.12.0 → 4.13.0

package/dist/esm/validateNavigationDestinations.d.ts

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

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

@@ -1 +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"}
+{"version":3,"file":"validateNavigationDestinations.d.ts","sourceRoot":"","sources":["../../validateNavigationDestinations.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAsB,MAAM,cAAc,CAAC;AAKxE,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CAAC;AAQnE,wBAAgB,8BAA8B,CAC1C,YAAY,EAAE,oBAAoB,EAAE,EACpC,QAAQ,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAA;CAAO,GAClI,+BAA+B,EAAE,CAEnC"}

package/dist/esm/validateNavigationDestinations.js

@@ -1,45 +1,19 @@
+import { diagnoseNavigation } from './navigation/diagnoseNavigation.js';
+
 // 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.
+ * Validates destinations against the outlet/route declarations owned by layouts and templates, and - when
+ * the screens and dialog templates are given - against the targets that actually exist.
+ *
+ * A shorthand for {@link diagnoseNavigation} over destinations without entry identities.
  */ 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;
+    return diagnoseNavigation({
+        entries: destinations.map((destination)=>({
+                destination
+            })),
+        ...surfaces
+    });
 }
 
 export { validateNavigationDestinations };

package/dist/esm/validateNavigationDestinations.js.map

@@ -1 +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;;"}
+{"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, DialogTemplate, Layout, Screen, ScreenTemplate } from '@cratis/scene.model';\nimport { NavigationDiagnostic, diagnoseNavigation } from './navigation';\n\n/**\n * A navigation problem as {@link validateNavigationDestinations} reports it.\n */\nexport type NavigationDestinationDiagnostic = NavigationDiagnostic;\n\n/**\n * Validates destinations against the outlet/route declarations owned by layouts and templates, and - when\n * the screens and dialog templates are given - against the targets that actually exist.\n *\n * A shorthand for {@link diagnoseNavigation} over destinations without entry identities.\n */\nexport function validateNavigationDestinations(\n    destinations: DestinationReference[],\n    surfaces: { layouts?: Layout[]; screenTemplates?: ScreenTemplate[]; screens?: Screen[]; dialogTemplates?: DialogTemplate[] } = {},\n): NavigationDestinationDiagnostic[] {\n    return diagnoseNavigation({ entries: destinations.map(destination => ({ destination })), ...surfaces });\n}\n"],"names":["validateNavigationDestinations","destinations","surfaces","diagnoseNavigation","entries","map","destination"],"mappings":";;AAAA;AACA;AAUA;;;;;AAKC,IACM,SAASA,8BAAAA,CACZC,YAAoC,EACpCC,QAAAA,GAA+H,EAAE,EAAA;AAEjI,IAAA,OAAOC,kBAAAA,CAAmB;AAAEC,QAAAA,OAAAA,EAASH,YAAAA,CAAaI,GAAG,CAACC,CAAAA,eAAgB;AAAEA,gBAAAA;aAAY,CAAA,CAAA;AAAK,QAAA,GAAGJ;AAAS,KAAA,CAAA;AACzG;;"}

package/index.ts

@@ -27,11 +27,13 @@ export * from './resolvePackageDependencies';
 export * from './packageCatalog';
 export * from './resolveScreenTemplates';
 export * from './templateApplicability';
+export * from './templates';
 export * from './buildStarterProfile';
 export * from './incompatibleStarterThemes';
 export * from './ActionDispatcher';
 export * from './runActions';
 export * from './resolveBehaviors';
 export * from './resolveStrings';
+export * from './navigation';
 export * from './validateNavigationDestinations';
 export * from './editing';

package/navigation/NavigationDiagnostic.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 { NavigationDiagnosticCode } from './NavigationDiagnosticCode';
+
+/**
+ * One problem with how destinations, outlets and routes fit together.
+ */
+export interface NavigationDiagnostic {
+    /** What kind of problem this is. */
+    code: NavigationDiagnosticCode;
+
+    /** A sentence naming the destinations, outlets or screens involved. */
+    message: string;
+
+    /** The entry the problem was found on - its `id`, or `#<position>` when it has none. Absent for model-wide problems. */
+    entry?: string;
+}

package/navigation/NavigationDiagnosticCode.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What is wrong with a navigation destination. The values are shared with the C# engine so both report
+ * the same code for the same model.
+ */
+export enum NavigationDiagnosticCode {
+    /** Two destinations that go to different targets share one URL. */
+    DuplicateRoute = 'duplicateRoute',
+
+    /** Two surfaces declare an outlet with the same name, so a destination cannot tell them apart. */
+    DuplicateOutlet = 'duplicateOutlet',
+
+    /** A destination names an outlet that no layout or screen template declares. */
+    MissingOutlet = 'missingOutlet',
+
+    /** A destination names an outlet that cannot host what it opens. */
+    IncompatibleOutlet = 'incompatibleOutlet',
+
+    /** Screens are placed in outlets owned by each other, so composition never terminates. */
+    NavigationCycle = 'navigationCycle',
+
+    /** A destination opens a screen or dialog that does not exist, or names nothing to open. */
+    UnavailableTarget = 'unavailableTarget',
+}

package/navigation/NavigationEntry.ts

@@ -0,0 +1,16 @@
+// 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';
+
+/**
+ * One place in the model a user can navigate from - a navigation item, toolbar action or link - reduced to
+ * its stable identity and destination.
+ */
+export interface NavigationEntry {
+    /** Stable identity used to point at the entry in diagnostics. */
+    id?: string;
+
+    /** Where the entry takes the user. */
+    destination: DestinationReference;
+}

package/navigation/NavigationGraph.ts

@@ -0,0 +1,26 @@
+// 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, Screen, ScreenTemplate } from '@cratis/scene.model';
+import { NavigationEntry } from './NavigationEntry';
+
+/**
+ * Everything navigation diagnostics look at. The catalogs are optional: an absent catalog means "not known
+ * here", so targets in it are not reported as unavailable. An empty catalog means "known to be empty".
+ */
+export interface NavigationGraph {
+    /** The destinations to check, in authored order. */
+    entries: NavigationEntry[];
+
+    /** The screens destinations may open. */
+    screens?: Screen[];
+
+    /** The layouts that may own outlets. */
+    layouts?: Layout[];
+
+    /** The screen templates that may own outlets, and that give screens their semantic type. */
+    screenTemplates?: ScreenTemplate[];
+
+    /** The dialog templates dialog destinations may open. */
+    dialogTemplates?: DialogTemplate[];
+}

package/navigation/OutletOwner.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Outlet } from '@cratis/scene.model';
+
+/**
+ * An outlet together with the layout or screen template that declares it.
+ */
+export interface OutletOwner {
+    outlet: Outlet;
+    owner: string;
+    ownerKind: 'Layout' | 'ScreenTemplate';
+}

package/navigation/collectOutlets.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 { NavigationDiagnostic } from './NavigationDiagnostic';
+import { NavigationDiagnosticCode } from './NavigationDiagnosticCode';
+import { NavigationGraph } from './NavigationGraph';
+import { OutletOwner } from './OutletOwner';
+
+/**
+ * Indexes every declared outlet by name, keeping the first declaration and reporting each later one as a
+ * duplicate - a destination names an outlet only by name, so two of them are ambiguous.
+ */
+export function collectOutlets(graph: NavigationGraph, diagnostics: NavigationDiagnostic[]): Map<string, OutletOwner> {
+    const owners = new Map<string, OutletOwner>();
+    const surfaces = [
+        ...(graph.layouts ?? []).map(layout => ({ name: layout.name, kind: 'Layout' as const, outlets: layout.outlets ?? [] })),
+        ...(graph.screenTemplates ?? []).map(template => ({ name: template.name, kind: 'ScreenTemplate' as const, outlets: template.outlets ?? [] })),
+    ];
+
+    for (const surface of surfaces) {
+        for (const outlet of surface.outlets) {
+            const existing = owners.get(outlet.name);
+            if (existing) {
+                diagnostics.push({
+                    code: NavigationDiagnosticCode.DuplicateOutlet,
+                    message: `Outlet '${outlet.name}' is declared by both '${existing.owner}' and '${surface.name}'; destinations cannot tell them apart.`,
+                });
+                continue;
+            }
+
+            owners.set(outlet.name, { outlet, owner: surface.name, ownerKind: surface.kind });
+        }
+    }
+
+    return owners;
+}

package/navigation/diagnoseNavigation.ts

@@ -0,0 +1,136 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationKind, DestinationReference, Screen } from '@cratis/scene.model';
+import { collectOutlets } from './collectOutlets';
+import { findHostingCycles } from './findHostingCycles';
+import { NavigationDiagnostic } from './NavigationDiagnostic';
+import { NavigationDiagnosticCode } from './NavigationDiagnosticCode';
+import { NavigationGraph } from './NavigationGraph';
+import { NavigationRouteKey, authoredRouteKey, navigationTarget } from './navigationRoute';
+import { OutletOwner } from './OutletOwner';
+
+/**
+ * Diagnoses how destinations, outlets, routes and targets fit together: duplicate routes, duplicate,
+ * missing or incompatible outlets, hosting cycles and unavailable targets.
+ *
+ * Routes are compared by `routeKey` - by default the authored route override, since the engine constructs no
+ * URLs. Nothing is rewritten. The C# engine (`NavigationDiagnostics.Diagnose`) reports the same codes and
+ * messages in the same order for the same model; both are asserted against `navigation-diagnostic-fixtures.json`.
+ */
+export function diagnoseNavigation(graph: NavigationGraph, routeKey: NavigationRouteKey = authoredRouteKey): NavigationDiagnostic[] {
+    const diagnostics: NavigationDiagnostic[] = [];
+    const outlets = collectOutlets(graph, diagnostics);
+    const screens = graph.screens ? new Map(graph.screens.map(screen => [screen.name, screen])) : undefined;
+    const routes = new Map<string, { entry: string; target: string }>();
+    const hostedIn = new Map<string, string[]>();
+
+    graph.entries.forEach((navigationEntry, index) => {
+        const entry = navigationEntry.id ?? `#${index + 1}`;
+        const destination = navigationEntry.destination;
+        const kind = destination.kind ?? (destination.dialog ? DestinationKind.Dialog : DestinationKind.Outlet);
+        const report = (code: NavigationDiagnosticCode, message: string) => diagnostics.push({ code, message, entry });
+
+        if (!destination.screen && !destination.module && !destination.route && !destination.dialog) {
+            report(NavigationDiagnosticCode.UnavailableTarget, `Destination '${entry}' names no screen, stable identity, route or dialog.`);
+            return;
+        }
+
+        diagnoseTarget(graph, screens, destination, kind, entry, report);
+        const owner = diagnoseOutlet(graph, outlets, screens, destination, kind, entry, report);
+        if (owner?.ownerKind === 'ScreenTemplate' && destination.screen && screens?.has(destination.screen)) {
+            const hosts = graph.screens!.filter(screen => screen.screenTemplate === owner.owner).map(screen => screen.name);
+            hostedIn.set(destination.screen, [...new Set([...(hostedIn.get(destination.screen) ?? []), ...hosts])]);
+        }
+
+        const route = kind === DestinationKind.External ? undefined : routeKey(destination);
+        if (route) {
+            const target = navigationTarget(destination, kind);
+            const existing = routes.get(route);
+            if (!existing) {
+                routes.set(route, { entry, target });
+            } else if (existing.target !== target) {
+                report(NavigationDiagnosticCode.DuplicateRoute, `Route '${destination.route ?? route}' is used by destinations '${existing.entry}' and '${entry}', which open different targets.`);
+            }
+        }
+    });
+
+    for (const cycle of findHostingCycles(graph.screens?.map(screen => screen.name) ?? [], hostedIn)) {
+        diagnostics.push({
+            code: NavigationDiagnosticCode.NavigationCycle,
+            message: `Navigation cycle ${[...cycle, cycle[0]].join(' -> ')}: each screen is placed in an outlet owned by the next, so composition never terminates.`,
+        });
+    }
+
+    return diagnostics;
+}
+
+type Report = (code: NavigationDiagnosticCode, message: string) => void;
+
+function diagnoseTarget(
+    graph: NavigationGraph,
+    screens: Map<string, Screen> | undefined,
+    destination: DestinationReference,
+    kind: DestinationKind,
+    entry: string,
+    report: Report,
+) {
+    if (kind === DestinationKind.Dialog) {
+        if (!destination.dialog) {
+            report(NavigationDiagnosticCode.UnavailableTarget, `Dialog destination '${entry}' names no dialog.`);
+        } else if (graph.dialogTemplates && !graph.dialogTemplates.some(template => template.name === destination.dialog)) {
+            report(NavigationDiagnosticCode.UnavailableTarget, `Destination '${entry}' opens dialog '${destination.dialog}', which no dialog template provides.`);
+        }
+        return;
+    }
+
+    if (kind === DestinationKind.Outlet && destination.screen && screens && !screens.has(destination.screen)) {
+        report(NavigationDiagnosticCode.UnavailableTarget, `Destination '${entry}' opens screen '${destination.screen}', which does not exist.`);
+    }
+}
+
+function diagnoseOutlet(
+    graph: NavigationGraph,
+    outlets: Map<string, OutletOwner>,
+    screens: Map<string, Screen> | undefined,
+    destination: DestinationReference,
+    kind: DestinationKind,
+    entry: string,
+    report: Report,
+): OutletOwner | undefined {
+    if (!destination.outlet) return undefined;
+
+    if (kind !== DestinationKind.Outlet) {
+        const opens = kind === DestinationKind.Dialog ? 'a dialog' : 'an external target';
+        report(NavigationDiagnosticCode.IncompatibleOutlet, `Destination '${entry}' opens ${opens} but names outlet '${destination.outlet}'; only outlet destinations render in outlets.`);
+        return undefined;
+    }
+
+    const owner = outlets.get(destination.outlet);
+    if (!owner) {
+        report(NavigationDiagnosticCode.MissingOutlet, `Destination '${entry}' targets missing outlet '${destination.outlet}'.`);
+        return undefined;
+    }
+
+    const screen = destination.screen ? screens?.get(destination.screen) : undefined;
+    if (!screen) return owner;
+
+    if (owner.ownerKind === 'Layout' && screen.layout !== owner.owner) {
+        report(
+            NavigationDiagnosticCode.IncompatibleOutlet,
+            `Outlet '${owner.outlet.name}' belongs to layout '${owner.owner}', but destination '${entry}' places '${screen.name}', which renders in layout '${screen.layout}'.`,
+        );
+    }
+
+    if (owner.outlet.accepts) {
+        const type = graph.screenTemplates?.find(template => template.name === screen.screenTemplate)?.metadata?.type;
+        if (!type || !owner.outlet.accepts.includes(type)) {
+            report(
+                NavigationDiagnosticCode.IncompatibleOutlet,
+                `Outlet '${owner.outlet.name}' accepts ${owner.outlet.accepts.join(', ')} screens, but destination '${entry}' places '${screen.name}' of type '${type ?? 'untyped'}'.`,
+            );
+        }
+    }
+
+    return owner;
+}

package/navigation/findHostingCycles.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Finds cycles in a "renders inside" graph, where an edge from a screen to another means the first is
+ * placed in an outlet the second one's template owns. Screens are visited in the given order and edges in
+ * insertion order, so the same graph always yields the same cycles in the same order. Each set of screens
+ * is reported once, starting from the screen the walk reached it through.
+ */
+export function findHostingCycles(screens: string[], edges: Map<string, string[]>): string[][] {
+    const state = new Map<string, 'visiting' | 'done'>();
+    const stack: string[] = [];
+    const reported = new Set<string>();
+    const cycles: string[][] = [];
+
+    const visit = (screen: string) => {
+        state.set(screen, 'visiting');
+        stack.push(screen);
+        for (const host of edges.get(screen) ?? []) {
+            const hostState = state.get(host);
+            if (hostState === 'visiting') {
+                const cycle = stack.slice(stack.indexOf(host));
+                const key = [...cycle].sort().join('\u0000');
+                if (!reported.has(key)) {
+                    reported.add(key);
+                    cycles.push(cycle);
+                }
+            } else if (hostState === undefined) {
+                visit(host);
+            }
+        }
+        stack.pop();
+        state.set(screen, 'done');
+    };
+
+    for (const screen of screens) {
+        if (!state.has(screen)) visit(screen);
+    }
+
+    return cycles;
+}

package/navigation/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './NavigationDiagnostic';
+export * from './NavigationDiagnosticCode';
+export * from './NavigationEntry';
+export * from './NavigationGraph';
+export * from './diagnoseNavigation';
+export * from './navigationEntriesFrom';
+export * from './navigationRoute';

package/navigation/navigationEntriesFrom.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { NavigationItem } from '@cratis/scene.model';
+import { NavigationEntry } from './NavigationEntry';
+
+/**
+ * Turns navigation contributions into entries for {@link diagnoseNavigation}. A legacy item carrying only
+ * `targetScreen` becomes a destination for that screen, so old and new content are checked the same way.
+ */
+export function navigationEntriesFrom(items: NavigationItem[]): NavigationEntry[] {
+    return items.map(item => ({
+        id: item.id,
+        destination: item.destination ?? { screen: item.targetScreen, routeParameterBindings: item.routeParameterBindings },
+    }));
+}

package/navigation/navigationRoute.ts

@@ -0,0 +1,25 @@
+// 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';
+
+/**
+ * Decides which route a destination occupies, so destinations occupying the same one can be compared.
+ *
+ * The engine constructs no URLs (ADR-004), so it only compares what was authored. A renderer that derives
+ * routes from stable identities, or treats parameter spellings as equivalent, supplies its own key - the same
+ * derivation it uses when it builds the URL - and gets duplicate routes diagnosed by that rule instead.
+ */
+export type NavigationRouteKey = (destination: DestinationReference) => string | undefined;
+
+/** The default route key: the authored route override, trimmed, or none. */
+export const authoredRouteKey: NavigationRouteKey = destination => destination.route?.trim() || undefined;
+
+/**
+ * What a destination opens, so two destinations sharing a route are only a conflict when they open
+ * different things.
+ */
+export function navigationTarget(destination: DestinationReference, kind: string): string {
+    const identity = destination.screen ?? [destination.module, destination.feature, destination.slice].filter(part => part).join('.');
+    return [kind, identity, destination.dialog ?? '', destination.outlet ?? ''].join('|');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/scene.engine",
-    "version": "4.12.0",
+    "version": "4.13.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.12.0"
+        "@cratis/scene.model": "4.13.0"
     },
     "devDependencies": {
-        "@cratis/scene.model": "4.12.0"
+        "@cratis/scene.model": "4.13.0"
     }
 }

package/packageVersionRange.ts

@@ -42,6 +42,24 @@ export function isVersionSatisfiedBy(version: string, range: string | undefined)
     }
 }
 
+/**
+ * Whether a range is one {@link isVersionSatisfiedBy} understands. An empty range or `*` is valid and means
+ * "any version"; anything the parser cannot read is invalid, so declarations can be rejected up front
+ * instead of surfacing later as a conflict nobody can satisfy.
+ */
+export function isValidVersionRange(range: string | undefined): boolean {
+    const trimmed = range?.trim();
+    if (!trimmed || trimmed === '*') return true;
+    return parseVersion(splitRange(trimmed)[1]) !== undefined;
+}
+
+/**
+ * Whether a value is a `major.minor.patch` version, optionally with a pre-release or build suffix.
+ */
+export function isValidVersion(version: string | undefined): boolean {
+    return version !== undefined && version.trim().length > 0 && parseVersion(version) !== undefined;
+}
+
 type Version = [number, number, number];
 
 function splitRange(range: string): [string, string] {

package/templates/TemplateCatalogEntry.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { TemplateAttribution, TemplateCompatibility, TemplateScope } from '@cratis/scene.model';
+import { TemplateCatalogKind } from './TemplateCatalogKind';
+
+/**
+ * One template as a template browser reads it: what it is, where it comes from, what it needs and whether the
+ * active package set can use it.
+ */
+export interface TemplateCatalogEntry {
+    /** The package that provides the template. */
+    package: string;
+
+    /** The version of that package. */
+    packageVersion: string;
+
+    kind: TemplateCatalogKind;
+    name: string;
+    displayName?: string;
+    description?: string;
+    type?: string;
+    category?: string;
+    scopes?: TemplateScope[];
+    compatibility?: TemplateCompatibility;
+    attribution?: TemplateAttribution;
+    license?: string;
+    licenseUrl?: string;
+
+    /** Whether the template's metadata is complete and every requirement is met. */
+    compatible: boolean;
+
+    /** Why it is not - missing or invalid metadata, or an unmet Scene or package requirement. */
+    problems: string[];
+}

package/templates/TemplateCatalogKind.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Which kind of template a catalog entry describes.
+ */
+export enum TemplateCatalogKind {
+    Layout = 'Layout',
+    ScreenTemplate = 'ScreenTemplate',
+    DialogTemplate = 'DialogTemplate',
+}

package/templates/TemplateSource.ts

@@ -0,0 +1,15 @@
+// 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, ScenePackage, ScreenTemplate } from '@cratis/scene.model';
+
+/**
+ * A package and the templates it provides. A React `ScenePackageBundle` already has this shape, so hosts pass
+ * their approved bundles straight in.
+ */
+export interface TemplateSource {
+    manifest: ScenePackage;
+    layouts?: Layout[];
+    screenTemplates?: ScreenTemplate[];
+    dialogTemplates?: DialogTemplate[];
+}