@cratis/scene.engine 4.11.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/forms/CommandFormLayoutDiagnostic.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 { CommandFormLayoutDiagnosticCode } from './CommandFormLayoutDiagnosticCode';
+
+/**
+ * A validation problem in authored command-form geometry.
+ */
+export interface CommandFormLayoutDiagnostic {
+    code: CommandFormLayoutDiagnosticCode;
+    message: string;
+    path: string;
+}

package/forms/CommandFormLayoutDiagnosticCode.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.
+
+/**
+ * Diagnostic codes for command-form geometry validation.
+ */
+export enum CommandFormLayoutDiagnosticCode {
+    EmptyColumns = 'emptyColumns',
+    DuplicateColumn = 'duplicateColumn',
+    InvalidColumnIndex = 'invalidColumnIndex',
+    InvalidWidth = 'invalidWidth',
+    DuplicatePlacement = 'duplicatePlacement',
+    InvalidPlacement = 'invalidPlacement',
+    MissingField = 'missingField',
+    OutOfBoundsPlacement = 'outOfBoundsPlacement',
+}

package/forms/CommandFormLayoutDraft.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 { CommandFormLayout } from '@cratis/scene.model';
+import { CommandFormLayoutDiagnostic } from './CommandFormLayoutDiagnostic';
+
+/**
+ * Separates invalid editing state from the last committed form geometry.
+ */
+export interface CommandFormLayoutDraft {
+    committed: CommandFormLayout;
+    draft: CommandFormLayout;
+    diagnostics: CommandFormLayoutDiagnostic[];
+    isValid: boolean;
+}

package/forms/commitCommandFormLayoutDraft.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.
+
+import { CommandFormLayout } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+
+/**
+ * Commits a draft layout only when it is valid; otherwise returns the previous committed metadata.
+ */
+export function commitCommandFormLayoutDraft(draft: CommandFormLayoutDraft): CommandFormLayout {
+    return draft.isValid ? draft.draft : draft.committed;
+}

package/forms/defaultCommandFormLayout.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.
+
+import { CommandFormLayout, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * Backward-compatible command form geometry: one flexible column and no authored placements.
+ */
+export const defaultCommandFormLayout: CommandFormLayout = {
+    columns: [{ index: 1, width: { unit: FormWidthUnit.Fraction, value: 1 } }],
+    placements: [],
+};

package/forms/formWidthToCss.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 { FormWidth, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * Converts a platform-neutral form width to a browser CSS width token.
+ */
+export function formWidthToCss(width: FormWidth | undefined): string | undefined {
+    if (!width) return undefined;
+    switch (width.unit) {
+        case FormWidthUnit.Auto:
+            return 'auto';
+        case FormWidthUnit.Fraction:
+            return `${width.value ?? 1}fr`;
+        case FormWidthUnit.Pixels:
+            return `${width.value ?? 0}px`;
+        case FormWidthUnit.Percent:
+            return `${width.value ?? 0}%`;
+    }
+}

package/forms/index.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.
+
+export * from './CommandFormLayoutDiagnostic';
+export * from './CommandFormLayoutDiagnosticCode';
+export * from './CommandFormLayoutDraft';
+export * from './commitCommandFormLayoutDraft';
+export * from './defaultCommandFormLayout';
+export * from './formWidthToCss';
+export * from './normalizeCommandFormLayout';
+export * from './parseFormWidth';
+export * from './preserveDirtyCommandValues';
+export * from './resizeCommandFormColumn';
+export * from './updateCommandFormFieldPlacement';
+export * from './validateCommandFormLayout';

package/forms/normalizeCommandFormLayout.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandFormLayout, FormColumn, FormFieldPlacement, FormWidth, FormWidthUnit } from '@cratis/scene.model';
+import { defaultCommandFormLayout } from './defaultCommandFormLayout';
+import { parseFormWidth } from './parseFormWidth';
+
+export interface LegacyCommandFormInputGeometry {
+    property: string;
+    column?: number;
+    width?: string;
+}
+
+/**
+ * Normalizes authored command form layout, including legacy per-input column/width metadata.
+ */
+export function normalizeCommandFormLayout(layout: CommandFormLayout | undefined, inputs: readonly LegacyCommandFormInputGeometry[] = []): CommandFormLayout {
+    if (layout) return layout;
+    if (!inputs.length) return defaultCommandFormLayout;
+    const placements = inputs.map((input, index): FormFieldPlacement => ({
+        field: input.property,
+        row: index + 1,
+        column: positiveInteger(input.column) ?? 1,
+        width: parseFormWidth(input.width),
+    }));
+    const columnCount = Math.max(1, ...placements.map(placement => placement.column));
+    return {
+        columns: Array.from({ length: columnCount }, (_, index): FormColumn => ({ index: index + 1, width: fraction(1) })),
+        placements,
+    };
+}
+
+function fraction(value: number): FormWidth {
+    return { unit: FormWidthUnit.Fraction, value };
+}
+
+function positiveInteger(value: number | undefined): number | undefined {
+    return value !== undefined && Number.isInteger(value) && value > 0 ? value : undefined;
+}

package/forms/parseFormWidth.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FormWidth, FormWidthUnit } from '@cratis/scene.model';
+
+/**
+ * Parses a legacy width token into typed form geometry. Arbitrary strings are intentionally rejected.
+ */
+export function parseFormWidth(value: unknown): FormWidth | undefined {
+    if (!value || typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    if (trimmed === 'auto') return { unit: FormWidthUnit.Auto };
+    const match = /^([0-9]+(?:\.[0-9]+)?)(fr|px|%)$/.exec(trimmed);
+    if (!match) return undefined;
+    const widthValue = Number(match[1]);
+    if (!Number.isFinite(widthValue) || widthValue < 0) return undefined;
+    if (match[2] === 'fr') return { unit: FormWidthUnit.Fraction, value: widthValue };
+    if (match[2] === 'px') return { unit: FormWidthUnit.Pixels, value: widthValue };
+    return { unit: FormWidthUnit.Percent, value: widthValue };
+}

package/forms/preserveDirtyCommandValues.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.
+
+/**
+ * Merges refreshed command values without overwriting dirty fields a user is editing.
+ */
+export function preserveDirtyCommandValues(
+    current: Record<string, unknown>,
+    refreshed: Record<string, unknown>,
+    dirtyFields: ReadonlySet<string>,
+): Record<string, unknown> {
+    return Object.fromEntries(Object.entries(refreshed).map(([field, value]) => [field, dirtyFields.has(field) ? current[field] : value]));
+}

package/forms/resizeCommandFormColumn.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.
+
+import { CommandFormLayout, FormWidth } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+import { validateCommandFormLayout } from './validateCommandFormLayout';
+
+/**
+ * Resizes a column as draft geometry, keeping the last committed layout separate when invalid.
+ */
+export function resizeCommandFormColumn(
+    committed: CommandFormLayout,
+    columnIndex: number,
+    width: FormWidth,
+    fields: readonly string[] = [],
+): CommandFormLayoutDraft {
+    const draft: CommandFormLayout = {
+        ...committed,
+        columns: committed.columns.map(column => column.index === columnIndex ? { ...column, width } : column),
+    };
+    const diagnostics = validateCommandFormLayout(draft, fields);
+    return { committed, draft, diagnostics, isValid: diagnostics.length === 0 };
+}

package/forms/updateCommandFormFieldPlacement.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 { CommandFormLayout, FormFieldPlacement } from '@cratis/scene.model';
+import { CommandFormLayoutDraft } from './CommandFormLayoutDraft';
+import { validateCommandFormLayout } from './validateCommandFormLayout';
+
+/**
+ * Updates a field placement as draft geometry, keeping the committed layout separate when invalid.
+ */
+export function updateCommandFormFieldPlacement(
+    committed: CommandFormLayout,
+    placement: FormFieldPlacement,
+    fields: readonly string[] = [],
+): CommandFormLayoutDraft {
+    const draft: CommandFormLayout = {
+        ...committed,
+        placements: [...committed.placements.filter(existing => existing.field !== placement.field), placement],
+    };
+    const diagnostics = validateCommandFormLayout(draft, fields);
+    return { committed, draft, diagnostics, isValid: diagnostics.length === 0 };
+}

package/forms/validateCommandFormLayout.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CommandFormLayout, FormWidth, FormWidthUnit } from '@cratis/scene.model';
+import { CommandFormLayoutDiagnostic } from './CommandFormLayoutDiagnostic';
+import { CommandFormLayoutDiagnosticCode } from './CommandFormLayoutDiagnosticCode';
+
+/**
+ * Validates authored command-form geometry without rewriting invalid drafts.
+ */
+export function validateCommandFormLayout(layout: CommandFormLayout, fields: readonly string[] = []): CommandFormLayoutDiagnostic[] {
+    const diagnostics: CommandFormLayoutDiagnostic[] = [];
+    const columnIndexes = new Set<number>();
+    const knownFields = new Set(fields);
+
+    if (!layout.columns.length) diagnostics.push(problem(CommandFormLayoutDiagnosticCode.EmptyColumns, 'At least one column is required.', 'columns'));
+    layout.columns.forEach((column, index) => {
+        if (!Number.isInteger(column.index) || column.index < 1) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidColumnIndex, `Column ${index + 1} must have a one-based integer index.`, `columns.${index}.index`));
+        }
+        if (columnIndexes.has(column.index)) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.DuplicateColumn, `Column ${column.index} is declared more than once.`, `columns.${index}.index`));
+        }
+        columnIndexes.add(column.index);
+        validateWidth(column.width, `columns.${index}.width`, diagnostics);
+        validateWidth(column.minWidth, `columns.${index}.minWidth`, diagnostics);
+        validateWidth(column.maxWidth, `columns.${index}.maxWidth`, diagnostics);
+    });
+
+    validateWidth(layout.columnGap, 'columnGap', diagnostics);
+    validateWidth(layout.rowGap, 'rowGap', diagnostics);
+
+    const placements = new Set<string>();
+    layout.placements.forEach((placement, index) => {
+        if (!placement.field.trim()) diagnostics.push(problem(CommandFormLayoutDiagnosticCode.MissingField, 'A placement must name its field.', `placements.${index}.field`));
+        if (knownFields.size && !knownFields.has(placement.field)) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.MissingField, `Placement targets unknown field '${placement.field}'.`, `placements.${index}.field`));
+        }
+        if (placements.has(placement.field)) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.DuplicatePlacement, `Field '${placement.field}' is placed more than once.`, `placements.${index}.field`));
+        }
+        placements.add(placement.field);
+        if (!Number.isInteger(placement.row) || placement.row < 1 || !Number.isInteger(placement.column) || placement.column < 1 ||
+            (placement.rowSpan !== undefined && (!Number.isInteger(placement.rowSpan) || placement.rowSpan < 1)) ||
+            (placement.columnSpan !== undefined && (!Number.isInteger(placement.columnSpan) || placement.columnSpan < 1))) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidPlacement, `Placement for '${placement.field}' must use positive integer row, column and span values.`, `placements.${index}`));
+        }
+        const span = placement.columnSpan ?? 1;
+        if (layout.columns.length && placement.column + span - 1 > layout.columns.length) {
+            diagnostics.push(problem(CommandFormLayoutDiagnosticCode.OutOfBoundsPlacement, `Placement for '${placement.field}' extends beyond the declared columns.`, `placements.${index}.columnSpan`));
+        }
+        validateWidth(placement.width, `placements.${index}.width`, diagnostics);
+    });
+
+    return diagnostics;
+}
+
+function validateWidth(width: FormWidth | undefined, path: string, diagnostics: CommandFormLayoutDiagnostic[]): void {
+    if (!width) return;
+    if (!Object.values(FormWidthUnit).includes(width.unit)) {
+        diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidWidth, `Width at '${path}' uses an unsupported unit.`, path));
+        return;
+    }
+    if (width.unit === FormWidthUnit.Auto && width.value !== undefined) {
+        diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidWidth, `Automatic width at '${path}' must not carry a numeric value.`, path));
+    }
+    if (width.unit !== FormWidthUnit.Auto && (width.value === undefined || width.value < 0 || !Number.isFinite(width.value))) {
+        diagnostics.push(problem(CommandFormLayoutDiagnosticCode.InvalidWidth, `Width at '${path}' must carry a non-negative numeric value.`, path));
+    }
+}
+
+function problem(code: CommandFormLayoutDiagnosticCode, message: string, path: string): CommandFormLayoutDiagnostic {
+    return { code, message, path };
+}

package/index.ts

@@ -8,6 +8,7 @@ export * from './BindingDiagnostic';
 export * from './resolveBindingExpression';
 export * from './validateBindingExpression';
 export * from './renderElement';
+export * from './forms';
 export * from './elementKind';
 export * from './panelKind';
 export * from './flowNodeKind';
@@ -26,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;
+}