@cratis/scene.engine 4.2.0 → 4.3.0

package/editing/indexDocument.ts

@@ -0,0 +1,237 @@
+// 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, ExternalComponent, FlowArrangement, FlowContainer, FlowLeaf, FlowNode,
+    FreeformArrangement, FreeformSlotArrangement, Layout, LayoutType, SceneDocument, SceneElement, SceneNodeKind, Screen,
+    ScreenTemplate, Slot, FlowContainerKind,
+} from '@cratis/scene.model';
+import { isContentControl, isExternalComponent, isItemsControl, isPanel } from '../elementKind';
+import { isFlowContainer, isFlowLeaf, isFlowSlotLeaf } from '../flowNodeKind';
+import { isCanvas, isDockPanel, isGrid, isStackPanel, isWrapPanel } from '../panelKind';
+import { errorDiagnostic } from './diagnostics';
+import { DocumentIndex, DocumentPath, ListLocation, NodeRecord } from './DocumentIndex';
+import {
+    dialogTemplateNodeId, elementNodeId, flowNodeId, freeformNodeId, layoutNodeId, ownerArrangementId, placementNodeId,
+    screenNodeId, screenTemplateNodeId, slotNodeId,
+} from './nodeIds';
+
+type Owner = Layout | ScreenTemplate | DialogTemplate | Screen;
+
+interface OwnerContext {
+    owner: string;
+    ownerKind: SceneNodeKind;
+    ownerId: string;
+}
+
+interface Placement {
+    parentId?: string;
+    list?: ListLocation;
+    leafId?: string;
+    mirror?: NodeRecord['mirror'];
+}
+
+/**
+ * The layout type a panel element is, by its shape.
+ */
+export function panelLayoutType(element: SceneElement): LayoutType | undefined {
+    if (!isPanel(element)) return undefined;
+    if (isGrid(element)) return LayoutType.GridPanel;
+    if (isCanvas(element)) return LayoutType.Canvas;
+    if (isDockPanel(element)) return LayoutType.DockPanel;
+    if (isStackPanel(element)) return LayoutType.StackPanel;
+    if (isWrapPanel(element)) return LayoutType.WrapPanel;
+    return undefined;
+}
+
+/**
+ * The layout type a flow node is.
+ */
+export function flowLayoutType(node: FlowNode): LayoutType {
+    if (isFlowContainer(node)) {
+        switch (node.kind) {
+            case FlowContainerKind.Row: return LayoutType.FlowRow;
+            case FlowContainerKind.Column: return LayoutType.FlowColumn;
+            default: return LayoutType.FlowGrid;
+        }
+    }
+
+    return isFlowSlotLeaf(node) ? LayoutType.FlowSlotLeaf : LayoutType.FlowLeaf;
+}
+
+class Indexer {
+    readonly index: DocumentIndex = { nodes: new Map(), diagnostics: [] };
+
+    constructor(private readonly document: SceneDocument) {}
+
+    run(): DocumentIndex {
+        this.document.layouts.forEach((layout, position) =>
+            this.owner(layout, ['layouts', position], { owner: layout.name, ownerKind: SceneNodeKind.Layout, ownerId: layoutNodeId(layout.name) }, undefined));
+        this.document.screenTemplates.forEach((template, position) =>
+            this.owner(template, ['screenTemplates', position], { owner: template.name, ownerKind: SceneNodeKind.ScreenTemplate, ownerId: screenTemplateNodeId(template.name) }, 'content'));
+        this.document.dialogTemplates.forEach((dialog, position) =>
+            this.owner(dialog, ['dialogTemplates', position], { owner: dialog.name, ownerKind: SceneNodeKind.DialogTemplate, ownerId: dialogTemplateNodeId(dialog.name) }, 'content'));
+        this.document.screens.forEach((screen, position) =>
+            this.owner(screen, ['screens', position], { owner: screen.name, ownerKind: SceneNodeKind.Screen, ownerId: screenNodeId(screen.name) }, 'slotContent'));
+        return this.index;
+    }
+
+    private add(record: NodeRecord): boolean {
+        if (this.index.nodes.has(record.id)) return false;
+        this.index.nodes.set(record.id, record);
+        return true;
+    }
+
+    private owner(owner: Owner, path: DocumentPath, context: OwnerContext, contentKey: 'content' | 'slotContent' | undefined): void {
+        this.add({ id: context.ownerId, kind: context.ownerKind, typeId: context.ownerKind, label: owner.name, path, value: owner, owner: context.owner, ownerKind: context.ownerKind });
+
+        const content = contentKey === undefined ? undefined : (owner as unknown as Record<string, Record<string, SceneElement[]> | undefined>)[contentKey];
+        const ownsSlots = 'slots' in owner;
+        const declared: Slot[] = ownsSlots ? owner.slots : this.slotsAvailableTo(owner as Screen);
+        const slotNames = new Set<string>([...declared.map(slot => slot.name), ...Object.keys(content ?? {})]);
+
+        for (const name of slotNames) {
+            const slotId = slotNodeId(context.ownerId, name);
+            const declaration = ownsSlots ? declared.findIndex(slot => slot.name === name) : -1;
+            const contentPath: DocumentPath | undefined = contentKey === undefined ? undefined : [...path, contentKey, name];
+            this.add({
+                id: slotId, kind: SceneNodeKind.Slot, typeId: 'slot', label: name, path: declaration >= 0 ? [...path, 'slots', declaration] : contentPath!,
+                value: declaration >= 0 ? declared[declaration] : content?.[name], parentId: context.ownerId, owner: context.owner,
+                ownerKind: context.ownerKind, slotName: name, contentPath,
+            });
+
+            if (declaration >= 0 && declared[declaration].arrangement) {
+                this.arrangement(declared[declaration].arrangement!, [...path, 'slots', declaration, 'arrangement'], slotId, context);
+            }
+
+            (content?.[name] ?? []).forEach((element, position) =>
+                this.element(element, [...contentPath!, position], context, { parentId: slotId, list: { path: contentPath!, index: position } }));
+        }
+
+        if ('arrangement' in owner && owner.arrangement) {
+            this.arrangement(owner.arrangement, [...path, 'arrangement'], ownerArrangementId(context.ownerId), context, context.ownerId);
+        }
+
+        if ('contributions' in owner) {
+            owner.contributions.forEach((contribution, position) =>
+                this.element(contribution.content, [...path, 'contributions', position, 'content'], context, { parentId: context.ownerId }));
+        }
+    }
+
+    private slotsAvailableTo(screen: Screen): Slot[] {
+        const template = screen.screenTemplate === undefined ? undefined : this.document.screenTemplates.find(candidate => candidate.name === screen.screenTemplate);
+        if (template) return template.slots;
+        return this.document.layouts.find(candidate => candidate.name === screen.layout)?.slots ?? [];
+    }
+
+    private element(element: SceneElement, path: DocumentPath, context: OwnerContext, placement: Placement): boolean {
+        const id = elementNodeId(element.id);
+        const panelType = panelLayoutType(element);
+        const typeId = isExternalComponent(element) ? element.componentName
+            : (panelType ?? (isContentControl(element) ? 'contentControl' : (isItemsControl(element) ? 'itemsControl' : 'element')));
+        const properties = (element as ExternalComponent).properties;
+        const label = (typeof properties?.label === 'string' && properties.label)
+            || (isPanel(element) && (element as { name?: string }).name)
+            || (isExternalComponent(element) && element.name)
+            || typeId;
+
+        if (!this.add({
+            id, kind: SceneNodeKind.Element, typeId, label, path, value: element, owner: context.owner, ownerKind: context.ownerKind, ...placement,
+        })) {
+            this.index.diagnostics.push(errorDiagnostic(DiagnosticCode.DuplicateElementId, `The element id '${element.id}' is used more than once.`, { nodeId: id }));
+            return false;
+        }
+
+        if (isExternalComponent(element)) {
+            for (const [name, children] of Object.entries(element.slots)) {
+                children.forEach((child, position) =>
+                    this.element(child, [...path, 'slots', name, position], context, { parentId: id, list: { path: [...path, 'slots', name], index: position }, mirror: placement.mirror }));
+            }
+        } else if (isContentControl(element)) {
+            this.element(element.content, [...path, 'content'], context, { parentId: id, mirror: placement.mirror });
+        } else if (isItemsControl(element)) {
+            this.element(element.itemTemplate, [...path, 'itemTemplate'], context, { parentId: id, mirror: placement.mirror });
+        } else if (isPanel(element)) {
+            element.children.forEach((child, position) =>
+                this.element(child, [...path, 'children', position], context, { parentId: id, list: { path: [...path, 'children'], index: position }, mirror: placement.mirror }));
+        }
+
+        return true;
+    }
+
+    private arrangement(arrangement: unknown, path: DocumentPath, holderId: string, context: OwnerContext, parentId = holderId): void {
+        if ((arrangement as FlowArrangement).root !== undefined) {
+            const flow = arrangement as FlowArrangement;
+            this.flowNode(flow.root, [...path, 'root'], holderId, 'root', [], context, { parentId });
+            flow.overrides?.forEach((override, position) =>
+                this.flowNode(override.root, [...path, 'overrides', position, 'root'], holderId, `override${position}`, [], context, { parentId }));
+            return;
+        }
+
+        const variants = (arrangement as FreeformArrangement | FreeformSlotArrangement).variants;
+        if (!Array.isArray(variants)) return;
+
+        const freeformId = freeformNodeId(holderId);
+        this.add({ id: freeformId, kind: SceneNodeKind.Freeform, typeId: LayoutType.Freeform, label: 'Freeform', path, value: arrangement, parentId, owner: context.owner, ownerKind: context.ownerKind });
+
+        const firstCopy = new Map<string, DocumentPath>();
+        variants.forEach((variant, variantIndex) => {
+            (variant.placements as { element?: SceneElement; slotName?: string }[]).forEach((placement, placementIndex) => {
+                const placementPath = [...path, 'variants', variantIndex, 'placements', placementIndex];
+                const key = placement.element?.id ?? placement.slotName ?? String(placementIndex);
+                const placementId = placementNodeId(holderId, variantIndex, key);
+                this.add({
+                    id: placementId, kind: SceneNodeKind.Placement, typeId: 'placement', label: key, path: placementPath, value: placement,
+                    parentId: freeformId, owner: context.owner, ownerKind: context.ownerKind,
+                    list: { path: [...path, 'variants', variantIndex, 'placements'], index: placementIndex },
+                });
+
+                if (!placement.element) return;
+                const elementPath = [...placementPath, 'element'];
+                const known = this.index.nodes.get(elementNodeId(placement.element.id));
+                const original = firstCopy.get(placement.element.id);
+                if (known && original) {
+                    known.placementIds!.push(placementId);
+                    known.mirror!.others.push(elementPath);
+                    return;
+                }
+
+                firstCopy.set(placement.element.id, elementPath);
+                const mirror = { prefix: elementPath, others: [] as DocumentPath[] };
+                if (this.element(placement.element, elementPath, context, { parentId: placementId, mirror })) {
+                    this.index.nodes.get(elementNodeId(placement.element.id))!.placementIds = [placementId];
+                }
+            });
+        });
+
+        // Descendants of a freeform element carry the same mirror object, so a copy found later is seen by all of them.
+    }
+
+    private flowNode(node: FlowNode, path: DocumentPath, holderId: string, variant: string, indexPath: number[], context: OwnerContext, placement: Placement): void {
+        const id = flowNodeId(holderId, variant, indexPath);
+        const type = flowLayoutType(node);
+        this.add({ id, kind: SceneNodeKind.FlowNode, typeId: type, label: type, path, value: node, owner: context.owner, ownerKind: context.ownerKind, ...placement });
+
+        if (isFlowContainer(node)) {
+            (node as FlowContainer).children.forEach((child, position) =>
+                this.flowNode(child, [...path, 'children', position], holderId, variant, [...indexPath, position], context,
+                    { parentId: id, list: { path: [...path, 'children'], index: position } }));
+        } else if (isFlowLeaf(node)) {
+            this.element((node as FlowLeaf).content, [...path, 'content'], context, { parentId: id, leafId: id });
+        }
+
+    }
+}
+
+/**
+ * Indexes every addressable node of a document: layouts, templates, dialog templates, screens, their slots, the
+ * elements in them, and the flow and freeform arrangements that position them.
+ *
+ * The index is what inspection and editing look nodes up in. Duplicate element ids are reported, and the second
+ * occurrence is left out of the index.
+ *
+ * @param document The document to index.
+ */
+export function indexDocument(document: SceneDocument): DocumentIndex {
+    return new Indexer(document).run();
+}

package/editing/inspect.ts

@@ -0,0 +1,142 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    DiagnosticCode, EditTarget, InspectedCollectionItem, InspectedProperty, NodeInspection,
+    NodeProvenance, ProvenanceKind, PropertyDescriptor, PropertyValueType, SceneDiagnostic, SceneDocument, SceneNodeKind, ValueSource,
+} from '@cratis/scene.model';
+import { describeNode, readNodeValue } from './describeNode';
+import { EditingContext } from './EditingContext';
+import { computeExposureGrants, ExposureGrant, grantKey } from './exposureGrants';
+import { indexDocument } from './indexDocument';
+import { NodeRecord } from './DocumentIndex';
+import { resolveEffectiveConfiguration } from './resolveEffectiveConfiguration';
+import { resolveTemplateChain } from './resolveTemplateChain';
+import { TemplateChain } from './TemplateChain';
+
+/**
+ * Works out whether a node is the editing scope's own, and when it is not, where it comes from and whether any of
+ * it is configurable here.
+ *
+ * @param record The node.
+ * @param chain The chain the scope sits in.
+ * @param scopeGrants What the scope's own instance may configure.
+ */
+export function provenanceOf(record: NodeRecord, chain: TemplateChain, scopeGrants: Map<string, ExposureGrant> | undefined): NodeProvenance {
+    const scopeLevel = chain.levels.at(-1);
+    if (scopeLevel && record.owner === scopeLevel.owner && record.ownerKind === scopeLevel.kind) return { kind: ProvenanceKind.Local };
+
+    const configurable = record.kind === SceneNodeKind.Element
+        && [...(scopeGrants?.values() ?? [])].some(grant => grant.component === (record.value as { id: string }).id);
+    return { kind: configurable ? ProvenanceKind.ConfigurableInherited : ProvenanceKind.Inherited, source: record.owner };
+}
+
+function isRemovable(record: NodeRecord, provenance: NodeProvenance): boolean {
+    return provenance.kind === ProvenanceKind.Local
+        && (record.list !== undefined || record.leafId !== undefined || record.placementIds !== undefined);
+}
+
+function toInspectedItems(raw: unknown, local: boolean): InspectedCollectionItem[] {
+    return (Array.isArray(raw) ? raw : []).map((item: Record<string, unknown>, position) => {
+        const { id, ...values } = item;
+        return { id: typeof id === 'string' ? id : `owner-${position}`, values, origin: 'owner', editable: local };
+    });
+}
+
+function inspectProperty(
+    descriptor: PropertyDescriptor,
+    record: NodeRecord,
+    provenance: NodeProvenance,
+    scopeInstance: string | undefined,
+    grants: Map<string, ExposureGrant> | undefined,
+    configuredValues: { path: string; value: unknown; source: string; items?: { id: string; values: Record<string, unknown>; origin: string }[] }[] | undefined,
+): InspectedProperty {
+    const currentValue = readNodeValue(record, descriptor.path);
+    const configured = configuredValues?.find(candidate => candidate.path === descriptor.path);
+    const local = provenance.kind === ProvenanceKind.Local;
+    const isCollection = descriptor.valueType === PropertyValueType.Collection;
+
+    const inspected: InspectedProperty = {
+        descriptor,
+        currentValue,
+        effectiveValue: configured ? configured.value : (currentValue ?? descriptor.default),
+        source: (configured?.source ?? (currentValue === undefined ? ValueSource.Default : ValueSource.Local)) as ValueSource,
+        editable: false,
+    };
+
+    const grant = !local && record.kind === SceneNodeKind.Element
+        ? grants?.get(grantKey((record.value as { id: string }).id, descriptor.path))
+        : undefined;
+
+    if (local) {
+        inspected.editable = descriptor.readOnly !== true;
+        if (inspected.editable) inspected.editTarget = EditTarget.Node;
+        else inspected.reason = 'This property is read-only.';
+    } else if (grant) {
+        inspected.editable = true;
+        inspected.editTarget = EditTarget.Instance;
+        if (isCollection) inspected.operations = grant.operations;
+    } else {
+        inspected.reason = `Inherited from '${provenance.source}', which does not expose it.`;
+    }
+
+    if (isCollection) {
+        const items = configured?.items
+            ? configured.items.map(item => ({ ...item, editable: local || (item.origin === scopeInstance && grant !== undefined && grant.operations.length > 0) }))
+            : toInspectedItems(currentValue, local);
+        inspected.items = items;
+    }
+
+    return inspected;
+}
+
+/**
+ * Describes one node for an editor: what it is, where it comes from, what can be edited on it - with current and
+ * effective values and effective editability - and what can be done with it.
+ *
+ * A property of a node the scope owns is edited on the node. A property of an inherited node is editable only
+ * when its owner exposed it, and then the edit goes to an instance contribution, never into the inherited node.
+ * Nothing is mutated.
+ *
+ * @param document The document to read.
+ * @param nodeId The node to describe; see the node id functions.
+ * @param context The catalog and the editing scope.
+ * @returns The inspection, or `undefined` when the document has no such node.
+ */
+export function inspect(document: SceneDocument, nodeId: string, context: EditingContext): NodeInspection | undefined {
+    const index = indexDocument(document);
+    const record = index.nodes.get(nodeId);
+    if (!record) return undefined;
+
+    const chain = resolveTemplateChain(document, context.scope);
+    const grants = computeExposureGrants(chain, context.catalog);
+    const scopeInstance = chain.levels.at(-1)?.instance;
+    const scopeGrants = scopeInstance === undefined ? undefined : grants.byInstance.get(scopeInstance);
+    const configuration = resolveEffectiveConfiguration(chain, document.instanceContributions, context.catalog);
+
+    const provenance = provenanceOf(record, chain, scopeGrants);
+    const description = describeNode(record, context.catalog);
+    const componentId = record.kind === SceneNodeKind.Element ? (record.value as { id: string }).id : undefined;
+    const configuredValues = configuration.components.find(candidate => candidate.component === componentId)?.values;
+
+    const diagnostics: SceneDiagnostic[] = [
+        ...description.diagnostics,
+        ...configuration.diagnostics.filter(diagnostic => diagnostic.component !== undefined && diagnostic.component === componentId),
+    ];
+    if (chain.levels.length === 0) {
+        diagnostics.push(...chain.diagnostics.filter(diagnostic => diagnostic.code === DiagnosticCode.UnknownScope));
+    }
+
+    return {
+        nodeId,
+        kind: record.kind,
+        typeId: record.typeId,
+        label: record.label,
+        parentId: record.parentId,
+        provenance,
+        properties: description.properties.map(descriptor => inspectProperty(descriptor, record, provenance, scopeInstance, scopeGrants, configuredValues)),
+        capabilities: description.capabilities,
+        removable: isRemovable(record, provenance),
+        diagnostics,
+    };
+}

package/editing/instanceEdits.ts

@@ -0,0 +1,243 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    AddCollectionItemEdit, CollectionOperation, ContributedItem, DiagnosticCode, EditCollectionItemEdit, InstanceContribution,
+    PropertyValueType, RemoveCollectionItemEdit, ReorderCollectionItemEdit, ResetInstanceValueEdit, SceneDiagnostic,
+    SceneDocument, SetInstanceValueEdit,
+} from '@cratis/scene.model';
+import { errorDiagnostic } from './diagnostics';
+import { EditSession } from './EditSession';
+import { ExposureGrant, grantKey } from './exposureGrants';
+import { cloneData } from './pathAccess';
+import { checkValue } from './propertyEdits';
+import { validateItemValues } from './validateValue';
+
+interface InstanceEditTarget {
+    instance: string;
+    component: string;
+    path: string;
+}
+
+function resolveGrant(session: EditSession, edit: InstanceEditTarget & { instance?: string }, diagnostics: SceneDiagnostic[]): { instance: string; grant: ExposureGrant } | undefined {
+    const context = { instance: edit.instance, component: edit.component, path: edit.path };
+    const instance = session.scopeInstance;
+    if (instance === undefined) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownScope, `There is no ${session.context.scope.kind} named '${session.context.scope.name}'.`, context));
+        return undefined;
+    }
+
+    if (edit.instance !== undefined && edit.instance !== instance) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownInstance, `Edits are made as '${instance}', not as '${edit.instance}'.`, context));
+        return undefined;
+    }
+
+    const grant = session.scopeGrants.get(grantKey(edit.component, edit.path));
+    if (!grant) {
+        diagnostics.push(errorDiagnostic(
+            DiagnosticCode.ContributionNotExposed,
+            `'${edit.path}' on '${edit.component}' is not exposed to '${instance}'. An owner exposes it, and each template between re-exposes it.`,
+            { ...context, instance }));
+        return undefined;
+    }
+
+    return { instance, grant };
+}
+
+function findContribution(clone: SceneDocument, instance: string, component: string, path: string): InstanceContribution | undefined {
+    return clone.instanceContributions.find(contribution =>
+        contribution.instance === instance && contribution.component === component && contribution.path === path);
+}
+
+function permitted(grant: ExposureGrant, operation: CollectionOperation, instance: string, diagnostics: SceneDiagnostic[]): boolean {
+    if (grant.descriptor.valueType !== PropertyValueType.Collection) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, `'${grant.descriptor.label}' is not a collection.`, { instance, component: grant.component, path: grant.path }));
+        return false;
+    }
+
+    if (!grant.operations.includes(operation)) {
+        diagnostics.push(errorDiagnostic(
+            DiagnosticCode.ContributionOperationNotPermitted,
+            `'${grant.descriptor.label}' does not allow '${operation}' from '${instance}'.`,
+            { instance, component: grant.component, path: grant.path }));
+        return false;
+    }
+
+    return true;
+}
+
+function checkFields(grant: ExposureGrant, values: Record<string, unknown>, itemId: string, instance: string, diagnostics: SceneDiagnostic[], requireAll: boolean): boolean {
+    const context = { instance, component: grant.component, path: grant.path, itemId };
+    let valid = true;
+
+    for (const field of Object.keys(values)) {
+        const known = grant.descriptor.item?.properties.some(candidate => candidate.path === field) ?? false;
+        if (known && grant.editableFields !== undefined && !grant.editableFields.includes(field)) {
+            diagnostics.push(errorDiagnostic(DiagnosticCode.ContributionOperationNotPermitted, `The field '${field}' of '${grant.descriptor.label}' is not exposed for editing.`, context));
+            valid = false;
+        }
+    }
+
+    const itemDescriptor = grant.descriptor.item;
+    const problems = validateItemValues(itemDescriptor, values).filter(problem => requireAll || problem.problem !== 'a value is required');
+    for (const problem of problems) {
+        diagnostics.push(errorDiagnostic(
+            problem.problem.startsWith('is not a field') ? DiagnosticCode.UnknownCollectionField : DiagnosticCode.InvalidValue,
+            `'${problem.field}' ${problem.problem}.`,
+            context));
+        valid = false;
+    }
+
+    return valid;
+}
+
+function ownItems(clone: SceneDocument, instance: string, grant: ExposureGrant): { contribution: InstanceContribution | undefined; items: ContributedItem[] } {
+    const contribution = findContribution(clone, instance, grant.component, grant.path);
+    return { contribution, items: contribution?.items ?? [] };
+}
+
+function save(clone: SceneDocument, instance: string, grant: ExposureGrant, existing: InstanceContribution | undefined, items: ContributedItem[]): void {
+    if (items.length === 0) {
+        if (existing) clone.instanceContributions.splice(clone.instanceContributions.indexOf(existing), 1);
+        return;
+    }
+
+    if (existing) existing.items = items;
+    else clone.instanceContributions.push({ instance, component: grant.component, path: grant.path, items });
+}
+
+/**
+ * Applies a scalar value set from the editing scope's instance to a copy of the document.
+ */
+export function applySetInstanceValue(session: EditSession, edit: SetInstanceValueEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveGrant(session, { ...edit, instance: edit.instance } as InstanceEditTarget, diagnostics);
+    if (!resolved) return;
+
+    if (resolved.grant.descriptor.valueType === PropertyValueType.Collection) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidEdit, `'${resolved.grant.descriptor.label}' is a collection; add, remove, reorder and edit its items instead.`, { instance: resolved.instance, component: edit.component, path: edit.path }));
+        return;
+    }
+
+    if (!checkValue(session, resolved.grant.descriptor, edit.value, { component: edit.component, instance: resolved.instance }, diagnostics)) return;
+
+    const existing = findContribution(clone, resolved.instance, edit.component, edit.path);
+    if (existing) existing.value = cloneData(edit.value);
+    else clone.instanceContributions.push({ instance: resolved.instance, component: edit.component, path: edit.path, value: cloneData(edit.value) });
+}
+
+/**
+ * Applies a reset to a copy of the document: the instance's contribution is removed, so the inherited value applies.
+ */
+export function applyResetInstanceValue(session: EditSession, edit: ResetInstanceValueEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveGrant(session, edit as InstanceEditTarget, diagnostics);
+    if (!resolved) return;
+
+    const existing = findContribution(clone, resolved.instance, edit.component, edit.path);
+    if (existing) clone.instanceContributions.splice(clone.instanceContributions.indexOf(existing), 1);
+}
+
+/**
+ * Applies an item addition to a copy of the document.
+ */
+export function applyAddCollectionItem(session: EditSession, edit: AddCollectionItemEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveGrant(session, edit as InstanceEditTarget, diagnostics);
+    if (!resolved || !permitted(resolved.grant, CollectionOperation.Add, resolved.instance, diagnostics)) return;
+
+    const { grant, instance } = resolved;
+    const context = { instance, component: edit.component, path: edit.path, itemId: edit.item.id };
+    if (typeof edit.item.id !== 'string' || edit.item.id.length === 0) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidValue, 'An item needs an id.', context));
+        return;
+    }
+
+    const effective = session.configuration.components.find(candidate => candidate.component === edit.component)?.values.find(value => value.path === edit.path);
+    const existingItems = effective?.items ?? [];
+    if (existingItems.some(item => item.id === edit.item.id)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.DuplicateCollectionItem, `The item id '${edit.item.id}' is already used.`, context));
+        return;
+    }
+
+    const maximum = grant.descriptor.constraints?.maximumItems;
+    if (maximum !== undefined && existingItems.length >= maximum) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidValue, `'${grant.descriptor.label}' allows at most ${maximum} items.`, context));
+        return;
+    }
+
+    if (!checkFields(grant, edit.item.values, edit.item.id, instance, diagnostics, true)) return;
+
+    const { contribution, items } = ownItems(clone, instance, grant);
+    if (edit.index !== undefined && (!Number.isInteger(edit.index) || edit.index < 0 || edit.index > items.length)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.IndexOutOfRange, `There is no position ${edit.index} among ${items.length} items.`, context));
+        return;
+    }
+
+    const next = [...items];
+    next.splice(edit.index ?? next.length, 0, cloneData(edit.item));
+    save(clone, instance, grant, contribution, next);
+}
+
+function findOwnItem(items: ContributedItem[], itemId: string, instance: string, grant: ExposureGrant, session: EditSession, diagnostics: SceneDiagnostic[]): number {
+    const position = items.findIndex(item => item.id === itemId);
+    if (position >= 0) return position;
+
+    const effective = session.configuration.components.find(candidate => candidate.component === grant.component)?.values.find(value => value.path === grant.path);
+    const fixed = effective?.items?.find(item => item.id === itemId);
+    diagnostics.push(errorDiagnostic(
+        fixed ? DiagnosticCode.ContributionOperationNotPermitted : DiagnosticCode.CollectionItemNotFound,
+        fixed ? `The item '${itemId}' belongs to '${fixed.origin}' and cannot be changed from '${instance}'.` : `'${instance}' has no item '${itemId}' in '${grant.descriptor.label}'.`,
+        { instance, component: grant.component, path: grant.path, itemId }));
+    return -1;
+}
+
+/**
+ * Applies an item removal to a copy of the document.
+ */
+export function applyRemoveCollectionItem(session: EditSession, edit: RemoveCollectionItemEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveGrant(session, edit as InstanceEditTarget, diagnostics);
+    if (!resolved || !permitted(resolved.grant, CollectionOperation.Remove, resolved.instance, diagnostics)) return;
+
+    const { contribution, items } = ownItems(clone, resolved.instance, resolved.grant);
+    const position = findOwnItem(items, edit.itemId, resolved.instance, resolved.grant, session, diagnostics);
+    if (position < 0) return;
+
+    save(clone, resolved.instance, resolved.grant, contribution, items.filter((_, index) => index !== position));
+}
+
+/**
+ * Applies an item reorder to a copy of the document.
+ */
+export function applyReorderCollectionItem(session: EditSession, edit: ReorderCollectionItemEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveGrant(session, edit as InstanceEditTarget, diagnostics);
+    if (!resolved || !permitted(resolved.grant, CollectionOperation.Reorder, resolved.instance, diagnostics)) return;
+
+    const { contribution, items } = ownItems(clone, resolved.instance, resolved.grant);
+    const position = findOwnItem(items, edit.itemId, resolved.instance, resolved.grant, session, diagnostics);
+    if (position < 0) return;
+
+    if (!Number.isInteger(edit.index) || edit.index < 0 || edit.index >= items.length) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.IndexOutOfRange, `There is no position ${edit.index} among ${items.length} items.`, { instance: resolved.instance, component: edit.component, path: edit.path, itemId: edit.itemId }));
+        return;
+    }
+
+    const next = [...items];
+    const [moved] = next.splice(position, 1);
+    next.splice(edit.index, 0, moved);
+    save(clone, resolved.instance, resolved.grant, contribution, next);
+}
+
+/**
+ * Applies an item field change to a copy of the document.
+ */
+export function applyEditCollectionItem(session: EditSession, edit: EditCollectionItemEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveGrant(session, edit as InstanceEditTarget, diagnostics);
+    if (!resolved || !permitted(resolved.grant, CollectionOperation.EditFields, resolved.instance, diagnostics)) return;
+
+    const { contribution, items } = ownItems(clone, resolved.instance, resolved.grant);
+    const position = findOwnItem(items, edit.itemId, resolved.instance, resolved.grant, session, diagnostics);
+    if (position < 0) return;
+
+    if (!checkFields(resolved.grant, { [edit.field]: edit.value }, edit.itemId, resolved.instance, diagnostics, false)) return;
+
+    const next = items.map((item, index) => index === position ? { ...item, values: { ...item.values, [edit.field]: cloneData(edit.value) } } : item);
+    save(clone, resolved.instance, resolved.grant, contribution, next);
+}