@cratis/scene.engine 4.2.0 → 4.3.0

package/editing/resolveEffectiveConfiguration.ts

@@ -0,0 +1,202 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    CollectionOperation, DiagnosticCode, EffectiveCollectionItem, EffectiveComponentConfiguration,
+    EffectiveConfiguration, EffectivePropertyValue, InstanceContribution, PropertyValueType, SceneDiagnostic, ValueSource,
+} from '@cratis/scene.model';
+import { DescriptorCatalog, findComponentDescriptor } from './DescriptorCatalog';
+import { errorDiagnostic } from './diagnostics';
+import { computeExposureGrants, ExposureGrant, grantKey } from './exposureGrants';
+import { cloneData, getValueAtPath, setValueAtPath } from './pathAccess';
+import { TemplateChain } from './TemplateChain';
+import { validateItemValues, validateValue } from './validateValue';
+
+/**
+ * Splits a flat collection item as it is stored on an element - `{ id, label, ... }` - into its id and fields.
+ */
+function toEffectiveItem(item: unknown, index: number): EffectiveCollectionItem {
+    const { id, ...values } = (item !== null && typeof item === 'object' ? item : {}) as Record<string, unknown>;
+    return { id: typeof id === 'string' && id.length > 0 ? id : `owner-${index}`, values, origin: 'owner', fixed: true };
+}
+
+function toFlatItem(item: EffectiveCollectionItem): Record<string, unknown> {
+    return { id: item.id, ...item.values };
+}
+
+function scalarValue(grant: ExposureGrant, matching: InstanceContribution[], instance: string, current: EffectivePropertyValue, diagnostics: SceneDiagnostic[]): void {
+    for (const contribution of matching) {
+        const problem = contribution.value === undefined ? 'a value is required' : validateValue(grant.descriptor, contribution.value);
+        if (problem) {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ContributionTypeMismatch,
+                `The saved value of '${grant.path}' set by '${instance}' is ignored: ${problem}. It is kept, and applies again when it fits.`,
+                { instance, component: grant.component, path: grant.path }));
+            continue;
+        }
+
+        current.value = contribution.value;
+        current.source = ValueSource.Instance;
+        current.contributedBy = instance;
+    }
+}
+
+function collectionValue(grant: ExposureGrant, matching: InstanceContribution[], instance: string, items: EffectiveCollectionItem[], diagnostics: SceneDiagnostic[]): boolean {
+    let contributed = false;
+
+    for (const contribution of matching) {
+        const context = { instance, component: grant.component, path: grant.path };
+        if (contribution.items === undefined) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.ContributionTypeMismatch, `The saved value of '${grant.path}' set by '${instance}' is ignored: a collection takes items.`, context));
+            continue;
+        }
+
+        if (contribution.items.length > 0 && !grant.operations.includes(CollectionOperation.Add)) {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ContributionOperationNotPermitted,
+                `'${instance}' has items in '${grant.path}', but adding items is not exposed. They are ignored and kept.`,
+                context));
+            continue;
+        }
+
+        for (const item of contribution.items) {
+            const itemContext = { ...context, itemId: item.id };
+            if (items.some(existing => existing.id === item.id)) {
+                diagnostics.push(errorDiagnostic(DiagnosticCode.DuplicateCollectionItem, `The item id '${item.id}' in '${grant.path}' is already used.`, itemContext));
+                continue;
+            }
+
+            const values: Record<string, unknown> = {};
+            for (const [field, value] of Object.entries(item.values)) {
+                if (grant.editableFields !== undefined && !grant.editableFields.includes(field)) {
+                    diagnostics.push(errorDiagnostic(DiagnosticCode.ContributionOperationNotPermitted, `The field '${field}' of '${grant.path}' is not exposed for editing.`, itemContext));
+                    continue;
+                }
+
+                const problem = validateItemValues(grant.descriptor.item, { [field]: value }).find(candidate => candidate.field === field);
+                if (problem) {
+                    diagnostics.push(errorDiagnostic(
+                        problem.problem.startsWith('is not a field') ? DiagnosticCode.UnknownCollectionField : DiagnosticCode.ContributionTypeMismatch,
+                        `The field '${field}' of an item in '${grant.path}' is ignored: ${problem.problem}.`,
+                        itemContext));
+                    continue;
+                }
+
+                values[field] = value;
+            }
+
+            items.push({ id: item.id, values, origin: instance, fixed: false });
+            contributed = true;
+        }
+    }
+
+    return contributed;
+}
+
+/**
+ * Resolves what every configurable component in a template chain is worth: the owner's own values, with each
+ * instance's contributions applied in nesting order.
+ *
+ * This is the one merge. The editor shows its result and the runtime renders from it, so what an author sees is
+ * what Play renders. Order is fixed: the owner's value first, then each level from the outermost inwards, so a
+ * later level wins a scalar and appends to a collection after the earlier ones.
+ *
+ * Nothing in the persisted data is changed. A contribution that cannot apply - the exposure was withdrawn, the
+ * property's type changed, the component is gone - is reported in `diagnostics` and left out of the result, and
+ * stays in `instanceContributions`, so restoring the exposure brings its value back.
+ *
+ * @param templateChain The nesting, from {@link resolveTemplateChain} or built by hand.
+ * @param instanceContributions What each instance has set.
+ * @param catalog The descriptors saying what each component supports.
+ */
+export function resolveEffectiveConfiguration(
+    templateChain: TemplateChain,
+    instanceContributions: InstanceContribution[],
+    catalog: DescriptorCatalog,
+): EffectiveConfiguration {
+    const grants = computeExposureGrants(templateChain, catalog);
+    const diagnostics: SceneDiagnostic[] = [...templateChain.diagnostics, ...grants.diagnostics];
+    const handled = new Set<InstanceContribution>();
+    const components = new Map<string, EffectiveComponentConfiguration>();
+
+    for (const grant of grants.exposed) {
+        const owner = templateChain.levels[grant.ownerLevel];
+        const element = owner.elements.find(candidate => candidate.id === grant.component)!;
+
+        let configuration = components.get(grant.component);
+        if (!configuration) {
+            configuration = { component: grant.component, owner: owner.owner, properties: cloneData(element.properties), values: [] };
+            components.set(grant.component, configuration);
+        }
+
+        const stored = getValueAtPath(element.properties, grant.path);
+        const base = stored === undefined ? cloneData(grant.descriptor.default) : cloneData(stored);
+        const isCollection = grant.descriptor.valueType === PropertyValueType.Collection;
+        const baseItems = isCollection && Array.isArray(base) ? base.map(toEffectiveItem) : [];
+        const items = [...baseItems];
+
+        const current: EffectivePropertyValue = {
+            path: grant.path,
+            value: base,
+            source: stored === undefined ? ValueSource.Default : ValueSource.Local,
+            inheritedValue: base,
+        };
+        let contributed = false;
+
+        for (let index = grant.ownerLevel + 1; index < templateChain.levels.length; index++) {
+            const instance = templateChain.levels[index].instance;
+            if (!grants.byInstance.get(instance)?.has(grantKey(grant.component, grant.path))) continue;
+
+            const effectiveGrant = grants.byInstance.get(instance)!.get(grantKey(grant.component, grant.path))!;
+            const matching = instanceContributions.filter(contribution =>
+                contribution.instance === instance && contribution.component === grant.component && contribution.path === grant.path);
+            for (const contribution of matching) handled.add(contribution);
+
+            if (isCollection) {
+                if (collectionValue(effectiveGrant, matching, instance, items, diagnostics)) {
+                    contributed = true;
+                    current.contributedBy = instance;
+                }
+            } else {
+                scalarValue(effectiveGrant, matching, instance, current, diagnostics);
+            }
+        }
+
+        if (isCollection) {
+            current.items = items;
+            current.inheritedValue = baseItems.map(toFlatItem);
+            current.value = items.map(toFlatItem);
+            if (contributed) current.source = ValueSource.Instance;
+        }
+
+        if (current.value !== undefined) setValueAtPath(configuration.properties, grant.path, current.value);
+        configuration.values.push(current);
+    }
+
+    const levelOf = new Map(templateChain.levels.map((chainLevel, index) => [chainLevel.instance, index]));
+    for (const contribution of instanceContributions) {
+        const contributorLevel = levelOf.get(contribution.instance);
+        if (contributorLevel === undefined || handled.has(contribution)) continue;
+
+        const context = { instance: contribution.instance, component: contribution.component, path: contribution.path };
+        const owner = templateChain.levels.slice(0, contributorLevel).find(chainLevel => chainLevel.elements.some(element => element.id === contribution.component));
+        if (!owner) {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ContributionTargetMissing,
+                `'${contribution.instance}' has saved values for '${contribution.component}', which is not in any layout or template above it. They are kept.`,
+                context));
+        } else if (!findComponentDescriptor(catalog, owner.elements.find(element => element.id === contribution.component)!.componentName)) {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.MissingComponentDescriptor,
+                `'${contribution.instance}' has saved values for '${contribution.component}', but nothing describes that component any more. They are kept.`,
+                context));
+        } else {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ContributionNotExposed,
+                `'${contribution.instance}' has a saved value for '${contribution.path}' on '${contribution.component}', which is not exposed to it. It is ignored and kept.`,
+                context));
+        }
+    }
+
+    return { components: [...components.values()], diagnostics };
+}

package/editing/resolveTemplateChain.ts

@@ -0,0 +1,109 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    DiagnosticCode, DialogTemplate, EditingScope, EditingScopeKind, ExposedProperty, Layout, SceneDocument,
+    SceneNodeKind, Screen, ScreenTemplate,
+} from '@cratis/scene.model';
+import { resolveScreenTemplates } from '../resolveScreenTemplates';
+import { collectComponents } from './collectComponents';
+import { errorDiagnostic, warningDiagnostic } from './diagnostics';
+import { TemplateChain, TemplateChainLevel } from './TemplateChain';
+
+function exposuresOf(document: SceneDocument, owner: string): ExposedProperty[] {
+    return document.exposures.find(declaration => declaration.owner === owner)?.properties ?? [];
+}
+
+function level(document: SceneDocument, kind: SceneNodeKind, prefix: string, owner: Layout | ScreenTemplate | DialogTemplate | Screen): TemplateChainLevel {
+    return {
+        owner: owner.name,
+        kind,
+        instance: `${prefix}:${owner.name}`,
+        elements: collectComponents(owner),
+        exposures: exposuresOf(document, owner.name),
+    };
+}
+
+function templateLevels(document: SceneDocument, layout: Layout, template: ScreenTemplate, chain: TemplateChain): TemplateChainLevel[] {
+    const placements = resolveScreenTemplates(layout, document.screenTemplates).placements;
+    const ancestry: ScreenTemplate[] = [template];
+
+    let current = template.name;
+    for (let guard = 0; guard <= document.screenTemplates.length; guard++) {
+        const placement = placements.find(candidate => candidate.template === current);
+        if (!placement || placement.container === layout.name) break;
+
+        const parent = document.screenTemplates.find(candidate => candidate.name === placement.container);
+        if (!parent) break;
+        ancestry.unshift(parent);
+        current = parent.name;
+    }
+
+    if (!placements.some(placement => placement.template === ancestry[0].name)) {
+        chain.diagnostics.push(warningDiagnostic(
+            DiagnosticCode.UnknownScope,
+            `The template '${ancestry[0].name}' could not be placed in the layout '${layout.name}', so nothing outside it is part of the chain.`));
+        return ancestry.slice(-1).map(item => level(document, SceneNodeKind.ScreenTemplate, 'template', item));
+    }
+
+    return ancestry.map(item => level(document, SceneNodeKind.ScreenTemplate, 'template', item));
+}
+
+/**
+ * Assembles the chain of owners an editing scope sits inside: the layout, each template down to the one the
+ * scope is in, and the scope itself.
+ *
+ * The same chain feeds {@link resolveEffectiveConfiguration} for the runtime and the editor, so both see the same
+ * nesting. A scope that cannot be found yields an empty chain with an error diagnostic.
+ *
+ * @param document The document to read.
+ * @param scope What is being edited.
+ * @returns The chain, outermost first.
+ */
+export function resolveTemplateChain(document: SceneDocument, scope: EditingScope): TemplateChain {
+    const chain: TemplateChain = { levels: [], diagnostics: [] };
+
+    switch (scope.kind) {
+        case EditingScopeKind.Layout: {
+            const layout = document.layouts.find(candidate => candidate.name === scope.name);
+            if (layout) chain.levels.push(level(document, SceneNodeKind.Layout, 'layout', layout));
+            break;
+        }
+
+        case EditingScopeKind.DialogTemplate: {
+            const dialog = document.dialogTemplates.find(candidate => candidate.name === scope.name);
+            if (dialog) chain.levels.push(level(document, SceneNodeKind.DialogTemplate, 'dialog', dialog));
+            break;
+        }
+
+        case EditingScopeKind.ScreenTemplate: {
+            const template = document.screenTemplates.find(candidate => candidate.name === scope.name);
+            const layout = document.layouts.find(candidate => candidate.name === scope.layout) ?? (scope.layout === undefined && document.layouts.length === 1 ? document.layouts[0] : undefined);
+            if (template && layout) {
+                chain.levels.push(level(document, SceneNodeKind.Layout, 'layout', layout), ...templateLevels(document, layout, template, chain));
+            } else if (template) {
+                chain.levels.push(level(document, SceneNodeKind.ScreenTemplate, 'template', template));
+            }
+
+            break;
+        }
+
+        default: {
+            const screen = document.screens.find(candidate => candidate.name === scope.name);
+            if (!screen) break;
+
+            const layout = document.layouts.find(candidate => candidate.name === screen.layout);
+            const template = screen.screenTemplate === undefined ? undefined : document.screenTemplates.find(candidate => candidate.name === screen.screenTemplate);
+            if (layout) chain.levels.push(level(document, SceneNodeKind.Layout, 'layout', layout));
+            if (layout && template) chain.levels.push(...templateLevels(document, layout, template, chain));
+            else if (template) chain.levels.push(level(document, SceneNodeKind.ScreenTemplate, 'template', template));
+            chain.levels.push(level(document, SceneNodeKind.Screen, 'screen', screen));
+        }
+    }
+
+    if (chain.levels.length === 0) {
+        chain.diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownScope, `There is no ${scope.kind} named '${scope.name}'.`));
+    }
+
+    return chain;
+}

package/editing/structureEdits.ts

@@ -0,0 +1,234 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    DiagnosticCode, FlowNode, InsertNodeEdit, MoveNodeEdit, RemoveNodeEdit, SceneDiagnostic, SceneDocument, SceneElement,
+    SceneNodeKind,
+} from '@cratis/scene.model';
+import { isExternalComponent, isPanel } from '../elementKind';
+import { errorDiagnostic } from './diagnostics';
+import { DocumentPath, NodeRecord } from './DocumentIndex';
+import { elementNodeId } from './nodeIds';
+import { ensureArrayAt, getAtPath, mirroredPaths } from './documentPaths';
+import { EditSession } from './EditSession';
+import { findLayoutTypeDescriptor } from './DescriptorCatalog';
+import { cloneData } from './pathAccess';
+
+/**
+ * Where an insert or move puts its node: the arrays (one per freeform size-class copy) and what they hold.
+ */
+interface InsertionPoint {
+    record: NodeRecord;
+    paths: DocumentPath[];
+
+    /** Whether the arrays hold flow nodes (and wrap elements in a leaf) or elements directly. */
+    flow: boolean;
+}
+
+function elementIdsIn(value: unknown, found: string[] = []): string[] {
+    if (value === null || typeof value !== 'object') return found;
+    if (Array.isArray(value)) {
+        for (const item of value) elementIdsIn(item, found);
+        return found;
+    }
+
+    const candidate = value as { id?: unknown; properties?: unknown };
+    if (typeof candidate.id === 'string' && candidate.properties !== null && typeof candidate.properties === 'object') found.push(candidate.id);
+    for (const child of Object.values(value)) elementIdsIn(child, found);
+    return found;
+}
+
+function resolveInsertionPoint(session: EditSession, targetId: string, slot: string | undefined, diagnostics: SceneDiagnostic[]): InsertionPoint | undefined {
+    const record = session.index.nodes.get(targetId);
+    const refuse = (code: DiagnosticCode, message: string) => {
+        diagnostics.push(errorDiagnostic(code, message, { nodeId: targetId }));
+        return undefined;
+    };
+
+    if (!record) return refuse(DiagnosticCode.UnknownNode, `There is no node '${targetId}'.`);
+    if (!session.isLocal(record)) return refuse(DiagnosticCode.NodeNotEditable, `'${targetId}' is inherited from '${session.sourceOf(record)}' and cannot be changed here.`);
+
+    const paths = (path: DocumentPath) => mirroredPaths(record.mirror, path);
+    switch (record.kind) {
+        case SceneNodeKind.Slot:
+            return record.contentPath
+                ? { record, paths: paths(record.contentPath), flow: false }
+                : refuse(DiagnosticCode.TargetDoesNotAcceptChildren, `'${record.label}' is a slot of a layout; a layout declares slots and screens fill them.`);
+
+        case SceneNodeKind.FlowNode:
+            return record.typeId === 'flowLeaf' || record.typeId === 'flowSlotLeaf'
+                ? refuse(DiagnosticCode.TargetDoesNotAcceptChildren, 'A flow leaf holds one element and takes no children; insert into its container.')
+                : { record, paths: paths([...record.path, 'children']), flow: true };
+
+        case SceneNodeKind.Element: {
+            const element = record.value as SceneElement;
+            if (isExternalComponent(element)) {
+                return slot
+                    ? { record, paths: paths([...record.path, 'slots', slot]), flow: false }
+                    : refuse(DiagnosticCode.UnknownSlot, `Say which slot of '${element.componentName}' to insert into.`);
+            }
+
+            return isPanel(element)
+                ? { record, paths: paths([...record.path, 'children']), flow: false }
+                : refuse(DiagnosticCode.TargetDoesNotAcceptChildren, `'${record.label}' holds a single element and takes no children.`);
+        }
+
+        default:
+            return refuse(DiagnosticCode.TargetDoesNotAcceptChildren, `'${record.label}' does not take children. Freeform arrangements place elements through their placements.`);
+    }
+}
+
+function checkCapacity(session: EditSession, point: InsertionPoint, current: number, diagnostics: SceneDiagnostic[]): boolean {
+    const maximum = findLayoutTypeDescriptor(session.context.catalog, point.record.typeId)?.capabilities.maximumChildren;
+    if (maximum !== undefined && current >= maximum) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.MaximumChildrenExceeded, `'${point.record.label}' holds at most ${maximum} children.`, { nodeId: point.record.id }));
+        return false;
+    }
+
+    return true;
+}
+
+function insertInto(session: EditSession, clone: SceneDocument, point: InsertionPoint, payload: SceneElement | FlowNode, isFlowNode: boolean, index: number | undefined, diagnostics: SceneDiagnostic[]): void {
+    if (isFlowNode && !point.flow) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, 'A flow node can only go into a flow container.', { nodeId: point.record.id }));
+        return;
+    }
+
+    const arrays = point.paths.map(path => ensureArrayAt(clone, path));
+    const length = arrays[0].length;
+    if (index !== undefined && (!Number.isInteger(index) || index < 0 || index > length)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.IndexOutOfRange, `There is no position ${index} among ${length} children.`, { nodeId: point.record.id }));
+        return;
+    }
+
+    if (!checkCapacity(session, point, length, diagnostics)) return;
+
+    for (const array of arrays) {
+        const node = point.flow && !isFlowNode ? { content: cloneData(payload) } : cloneData(payload);
+        array.splice(index ?? array.length, 0, node);
+    }
+}
+
+/**
+ * Applies an insert to a copy of the document.
+ */
+export function applyInsertNode(session: EditSession, edit: InsertNodeEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    if ((edit.element === undefined) === (edit.flowNode === undefined)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, 'Give exactly one of element and flowNode.', { nodeId: edit.target }));
+        return;
+    }
+
+    const point = resolveInsertionPoint(session, edit.target, edit.slot, diagnostics);
+    if (!point) return;
+
+    const identities = elementIdsIn(edit.element ?? edit.flowNode);
+    const duplicate = identities.find((identity, position) => identities.indexOf(identity) !== position || session.index.nodes.has(elementNodeId(identity)));
+    if (duplicate !== undefined) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ElementIdInUse, `The element id '${duplicate}' is already used.`, { nodeId: edit.target }));
+        return;
+    }
+
+    insertInto(session, clone, point, (edit.element ?? edit.flowNode)!, edit.flowNode !== undefined, edit.index, diagnostics);
+}
+
+interface Removal {
+    /** The list record whose array holds the node being taken out (a flow leaf for an element it wraps). */
+    holder: NodeRecord;
+    payload: SceneElement | FlowNode;
+    isFlowNode: boolean;
+}
+
+function resolveRemoval(session: EditSession, nodeId: string, diagnostics: SceneDiagnostic[]): Removal | undefined {
+    const record = session.index.nodes.get(nodeId);
+    if (!record) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownNode, `There is no node '${nodeId}'.`, { nodeId }));
+        return undefined;
+    }
+
+    if (!session.isLocal(record)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.NodeNotEditable, `'${nodeId}' is inherited from '${session.sourceOf(record)}' and cannot be changed here.`, { nodeId }));
+        return undefined;
+    }
+
+    const holder = record.leafId !== undefined ? session.index.nodes.get(record.leafId)! : record;
+    const isElement = record.kind === SceneNodeKind.Element;
+    const removable = holder.list !== undefined || (isElement && record.placementIds !== undefined);
+    if (!removable || (record.kind !== SceneNodeKind.Element && record.kind !== SceneNodeKind.FlowNode)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.NodeNotRemovable, `'${record.label}' cannot be moved or removed on its own.`, { nodeId }));
+        return undefined;
+    }
+
+    return { holder: isElement && record.placementIds !== undefined ? record : holder, payload: record.value as SceneElement | FlowNode, isFlowNode: !isElement };
+}
+
+function takeOut(session: EditSession, clone: SceneDocument, removal: Removal): void {
+    const { holder } = removal;
+    if (holder.placementIds !== undefined && holder.kind === SceneNodeKind.Element) {
+        for (const placementId of holder.placementIds) {
+            const placement = session.index.nodes.get(placementId)!;
+            const array = getAtPath(clone, placement.list!.path) as unknown[];
+            array.splice(placement.list!.index, 1);
+        }
+
+        return;
+    }
+
+    for (const path of mirroredPaths(holder.mirror, holder.list!.path)) {
+        const index = holder.list!.index;
+        (getAtPath(clone, path) as unknown[]).splice(index, 1);
+    }
+}
+
+/**
+ * Applies a removal to a copy of the document. Removing an element a flow leaf holds removes the leaf too, and
+ * removing a freeform element removes its placement in every size-class variant.
+ */
+export function applyRemoveNode(session: EditSession, edit: RemoveNodeEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const removal = resolveRemoval(session, edit.nodeId, diagnostics);
+    if (removal) takeOut(session, clone, removal);
+}
+
+/**
+ * Applies a move - a reorder or a reparent - to a copy of the document.
+ *
+ * `index` is the position the node ends up at among its new siblings. The destination arrays are located before
+ * anything is taken out, so removing a sibling that shifts the destination's own address does not misdirect the
+ * insert.
+ */
+export function applyMoveNode(session: EditSession, edit: MoveNodeEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const removal = resolveRemoval(session, edit.nodeId, diagnostics);
+    if (!removal) return;
+
+    const point = resolveInsertionPoint(session, edit.target, edit.slot, diagnostics);
+    if (!point) return;
+
+    const moved = session.index.nodes.get(edit.nodeId)!;
+    for (let ancestor: NodeRecord | undefined = point.record; ancestor; ancestor = ancestor.parentId === undefined ? undefined : session.index.nodes.get(ancestor.parentId)) {
+        if (ancestor.id === moved.id) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.ContainmentCycle, `'${moved.label}' cannot be moved into itself or something inside it.`, { nodeId: edit.nodeId }));
+            return;
+        }
+    }
+
+    const payload = cloneData(removal.payload);
+    const arrays = point.paths.map(path => ensureArrayAt(clone, path));
+    takeOut(session, clone, removal);
+
+    if (removal.isFlowNode && !point.flow) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, 'A flow node can only go into a flow container.', { nodeId: edit.nodeId }));
+        return;
+    }
+
+    const length = arrays[0].length;
+    if (edit.index !== undefined && (!Number.isInteger(edit.index) || edit.index < 0 || edit.index > length)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.IndexOutOfRange, `There is no position ${edit.index} among ${length} children.`, { nodeId: edit.target }));
+        return;
+    }
+
+    if (!checkCapacity(session, point, length, diagnostics)) return;
+
+    for (const array of arrays) {
+        const node = point.flow && !removal.isFlowNode ? { content: cloneData(payload) } : cloneData(payload);
+        array.splice(edit.index ?? array.length, 0, node);
+    }
+}

package/editing/validateBinding.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    DiagnosticCode, PropertyDescriptor, QueryBinding, QueryCandidate, SceneDiagnostic,
+} from '@cratis/scene.model';
+import { errorDiagnostic } from './diagnostics';
+
+/**
+ * The types of the values a binding can draw from, keyed by binding path. Supplied by the host, which knows what
+ * is in scope where the query is used.
+ */
+export interface BindingTypeScope {
+    types: Record<string, string>;
+}
+
+const integerTypes = new Set(['int', 'integer', 'int16', 'int32', 'int64', 'short', 'long', 'byte', 'uint', 'uint16', 'uint32', 'uint64']);
+const fractionalTypes = new Set(['number', 'float', 'double', 'decimal', 'single']);
+
+function normalizeType(type: string): string {
+    return type.trim().toLowerCase().replace(/\?$/, '');
+}
+
+/**
+ * Whether a value of one type can feed a parameter or field of another.
+ *
+ * Types compare by name. A whole number may feed a fractional one, never the reverse, and a type called `any` or
+ * `unknown` on either side matches anything.
+ */
+export function areTypesCompatible(sourceType: string, targetType: string): boolean {
+    const source = normalizeType(sourceType);
+    const target = normalizeType(targetType);
+    if (source === target || source === 'any' || target === 'any' || source === 'unknown' || target === 'unknown') return true;
+    if (integerTypes.has(source)) return integerTypes.has(target) || fractionalTypes.has(target);
+    return fractionalTypes.has(source) && fractionalTypes.has(target);
+}
+
+/**
+ * Validates a query binding against the query it names and the property it is for.
+ *
+ * Reports a query that is not among the candidates, a result shape the property cannot bind to, a required
+ * parameter nothing supplies, a binding for a parameter the query does not have, an argument whose type does not
+ * fit its parameter, and a result binding that names a field the query does not return.
+ *
+ * @param descriptor The `QueryReference` property the binding is the value of.
+ * @param candidate The candidate the binding names, or `undefined` when the host found none.
+ * @param binding The binding to check.
+ * @param scope The types of the values arguments draw from. Without it argument types are not checked.
+ * @returns The problems found; empty when the binding is sound.
+ */
+export function validateBinding(
+    descriptor: PropertyDescriptor,
+    candidate: QueryCandidate | undefined,
+    binding: QueryBinding,
+    scope?: BindingTypeScope,
+): SceneDiagnostic[] {
+    const path = descriptor.path;
+    if (!candidate || candidate.id !== binding.queryId) {
+        return [errorDiagnostic(DiagnosticCode.MissingQuery, `The query '${binding.query}' (${binding.queryId}) is not available here.`, { path })];
+    }
+
+    const diagnostics: SceneDiagnostic[] = [];
+    const allowedShapes = descriptor.constraints?.resultShapes;
+    if (allowedShapes && !allowedShapes.includes(candidate.resultShape)) {
+        diagnostics.push(errorDiagnostic(
+            DiagnosticCode.IncompatibleResultShape,
+            `'${descriptor.label}' binds to ${allowedShapes.join(' or ')} results, but '${candidate.name}' returns ${candidate.resultShape}.`,
+            { path }));
+    }
+
+    for (const argument of binding.arguments) {
+        const parameter = candidate.parameters.find(candidateParameter => candidateParameter.name === argument.parameter);
+        if (!parameter) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownParameter, `'${candidate.name}' has no parameter '${argument.parameter}'.`, { path }));
+            continue;
+        }
+
+        if (!scope) continue;
+        const sourceType = scope.types[argument.source.path];
+        if (sourceType === undefined) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.UnresolvedArgumentSource, `'${argument.source.path}' is not available to supply '${parameter.name}'.`, { path }));
+        } else if (!areTypesCompatible(sourceType, parameter.type)) {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.ArgumentTypeMismatch,
+                `'${argument.source.path}' is ${sourceType} but '${parameter.name}' expects ${parameter.type}.`,
+                { path }));
+        }
+    }
+
+    for (const parameter of candidate.parameters.filter(candidateParameter => candidateParameter.required)) {
+        if (!binding.arguments.some(argument => argument.parameter === parameter.name)) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.MissingRequiredParameter, `'${candidate.name}' needs a value for '${parameter.name}'.`, { path }));
+        }
+    }
+
+    for (const result of binding.results) {
+        if (!candidate.resultFields.some(field => field.name === result.field)) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownResultField, `'${candidate.name}' does not return a field '${result.field}'.`, { path }));
+        }
+    }
+
+    return diagnostics;
+}