@cratis/scene.engine 4.2.0 → 4.3.0

package/editing/layoutTypeDescriptors.ts

@@ -0,0 +1,191 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    HorizontalAlignment, LayoutChildPlacement, LayoutType, LayoutTypeDescriptor, Orientation, PropertyChoice,
+    PropertyDescriptor, PropertyValueType, VerticalAlignment, Visibility,
+} from '@cratis/scene.model';
+
+function choices(enumObject: Record<string, string>): PropertyChoice[] {
+    return Object.values(enumObject).map(value => ({ value, label: value }));
+}
+
+const spacing = (path: string, label: string, group: string): PropertyDescriptor => ({
+    path, label, group, valueType: PropertyValueType.Number, default: 0, constraints: { minimum: 0 },
+});
+
+const flowNodeProperties: PropertyDescriptor[] = [
+    {
+        path: 'grow', label: 'Grow', group: 'Layout', valueType: PropertyValueType.Number,
+        description: 'How much of the free space in its container this node takes, relative to its siblings.',
+        constraints: { minimum: 0 },
+    },
+    {
+        path: 'span', label: 'Span', group: 'Layout', valueType: PropertyValueType.Number,
+        description: 'How many grid columns this node spans. Only meaningful inside a grid.',
+        constraints: { minimum: 1, integer: true },
+    },
+];
+
+const flowContainerProperties: PropertyDescriptor[] = [spacing('gap', 'Gap', 'Layout'), ...flowNodeProperties];
+
+const panelProperties: PropertyDescriptor[] = [
+    { path: 'name', label: 'Name', group: 'General', valueType: PropertyValueType.String },
+    { path: 'visibility', label: 'Visibility', group: 'General', valueType: PropertyValueType.Enum, choices: choices(Visibility), default: Visibility.Visible },
+    { path: 'isEnabled', label: 'Enabled', group: 'General', valueType: PropertyValueType.Boolean, default: true },
+    { path: 'opacity', label: 'Opacity', group: 'General', valueType: PropertyValueType.Number, default: 1, constraints: { minimum: 0, maximum: 1 } },
+    { path: 'horizontalAlignment', label: 'Horizontal alignment', group: 'Layout', valueType: PropertyValueType.Enum, choices: choices(HorizontalAlignment) },
+    { path: 'verticalAlignment', label: 'Vertical alignment', group: 'Layout', valueType: PropertyValueType.Enum, choices: choices(VerticalAlignment) },
+    { path: 'zIndex', label: 'Stacking order', group: 'Layout', valueType: PropertyValueType.Number, default: 0, constraints: { integer: true } },
+];
+
+const orientation: PropertyDescriptor = {
+    path: 'orientation', label: 'Orientation', group: 'Layout', valueType: PropertyValueType.Enum, choices: choices(Orientation),
+};
+
+const panelChildren = { acceptsChildren: true, childPlacement: LayoutChildPlacement.Ordered, supportsSizeClassVariants: false };
+
+/**
+ * The layout type -> capability matrix, as data. Every {@link LayoutType} has exactly one entry; the
+ * documentation's matrix is this table.
+ */
+export const layoutTypeDescriptors: LayoutTypeDescriptor[] = [
+    {
+        type: LayoutType.FlowRow,
+        label: 'Row',
+        description: 'Reflows its children horizontally.',
+        capabilities: {
+            acceptsChildren: true, childPlacement: LayoutChildPlacement.Ordered, supportsGridSpan: false,
+            supportsSizeClassVariants: true, convertibleTo: [LayoutType.FlowColumn, LayoutType.FlowGrid],
+        },
+        properties: flowContainerProperties,
+    },
+    {
+        type: LayoutType.FlowColumn,
+        label: 'Column',
+        description: 'Reflows its children vertically.',
+        capabilities: {
+            acceptsChildren: true, childPlacement: LayoutChildPlacement.Ordered, supportsGridSpan: false,
+            supportsSizeClassVariants: true, convertibleTo: [LayoutType.FlowRow, LayoutType.FlowGrid],
+        },
+        properties: flowContainerProperties,
+    },
+    {
+        type: LayoutType.FlowGrid,
+        label: 'Grid',
+        description: 'Arranges its children in a grid; children can span columns.',
+        capabilities: {
+            acceptsChildren: true, childPlacement: LayoutChildPlacement.Ordered, supportsGridSpan: true,
+            supportsSizeClassVariants: true, convertibleTo: [LayoutType.FlowRow, LayoutType.FlowColumn],
+        },
+        properties: [
+            ...flowContainerProperties,
+            { path: 'columns', label: 'Columns', group: 'Layout', valueType: PropertyValueType.Number, constraints: { minimum: 1, integer: true } },
+            { path: 'rows', label: 'Rows', group: 'Layout', valueType: PropertyValueType.Number, constraints: { minimum: 1, integer: true } },
+        ],
+    },
+    {
+        type: LayoutType.FlowLeaf,
+        label: 'Content',
+        description: 'Positions one element within a flow.',
+        capabilities: {
+            acceptsChildren: false, maximumChildren: 1, childPlacement: LayoutChildPlacement.None, supportsGridSpan: true,
+            supportsSizeClassVariants: false, convertibleTo: [],
+        },
+        properties: flowNodeProperties,
+    },
+    {
+        type: LayoutType.FlowSlotLeaf,
+        label: 'Slot',
+        description: 'Positions one of the layout\'s own named slots within its arrangement.',
+        capabilities: {
+            acceptsChildren: false, childPlacement: LayoutChildPlacement.None, supportsGridSpan: true,
+            supportsSizeClassVariants: false, convertibleTo: [],
+        },
+        properties: [
+            { path: 'slotName', label: 'Slot', group: 'Layout', valueType: PropertyValueType.String, constraints: { required: true } },
+            ...flowNodeProperties,
+        ],
+    },
+    {
+        type: LayoutType.Freeform,
+        label: 'Freeform',
+        description: 'Places each child at its own position and size, one variant per size class.',
+        capabilities: {
+            acceptsChildren: true, childPlacement: LayoutChildPlacement.Positioned, supportsGridSpan: false,
+            supportsSizeClassVariants: true, convertibleTo: [],
+        },
+        properties: [],
+    },
+    {
+        type: LayoutType.StackPanel,
+        label: 'Stack panel',
+        description: 'Stacks its children in one direction with a fixed spacing.',
+        capabilities: { ...panelChildren, supportsGridSpan: false, convertibleTo: [LayoutType.WrapPanel, LayoutType.DockPanel] },
+        properties: [...panelProperties, orientation, spacing('spacing', 'Spacing', 'Layout')],
+    },
+    {
+        type: LayoutType.WrapPanel,
+        label: 'Wrap panel',
+        description: 'Lays children out along a line and wraps to the next when it is full.',
+        capabilities: { ...panelChildren, supportsGridSpan: false, convertibleTo: [LayoutType.StackPanel, LayoutType.DockPanel] },
+        properties: [
+            ...panelProperties,
+            orientation,
+            { path: 'itemWidth', label: 'Item width', group: 'Layout', valueType: PropertyValueType.Number, constraints: { minimum: 0 } },
+            { path: 'itemHeight', label: 'Item height', group: 'Layout', valueType: PropertyValueType.Number, constraints: { minimum: 0 } },
+        ],
+    },
+    {
+        type: LayoutType.DockPanel,
+        label: 'Dock panel',
+        description: 'Docks each child against an edge; the last child can fill what remains.',
+        capabilities: { ...panelChildren, supportsGridSpan: false, convertibleTo: [LayoutType.StackPanel, LayoutType.WrapPanel] },
+        properties: [
+            ...panelProperties,
+            { path: 'lastChildFill', label: 'Last child fills', group: 'Layout', valueType: PropertyValueType.Boolean, default: true },
+        ],
+    },
+    {
+        type: LayoutType.GridPanel,
+        label: 'Grid panel',
+        description: 'Positions children in rows and columns defined by the panel.',
+        capabilities: { ...panelChildren, supportsGridSpan: true, convertibleTo: [] },
+        properties: [
+            ...panelProperties,
+            { path: 'rows', label: 'Rows', group: 'Layout', valueType: PropertyValueType.Object, editorKind: 'gridDefinitions' },
+            { path: 'columns', label: 'Columns', group: 'Layout', valueType: PropertyValueType.Object, editorKind: 'gridDefinitions' },
+        ],
+    },
+    {
+        type: LayoutType.Canvas,
+        label: 'Canvas',
+        description: 'Places each child at an absolute position.',
+        capabilities: {
+            acceptsChildren: true, childPlacement: LayoutChildPlacement.Positioned, supportsGridSpan: false,
+            supportsSizeClassVariants: false, convertibleTo: [],
+        },
+        properties: [
+            ...panelProperties,
+            { path: 'extent', label: 'Extent', group: 'Layout', valueType: PropertyValueType.Object, editorKind: 'size' },
+        ],
+    },
+];
+
+/**
+ * The editable properties of a placement within a freeform variant - an element's or a slot's position and size.
+ */
+export const placementProperties: PropertyDescriptor[] = [
+    { path: 'x', label: 'Left', group: 'Placement', valueType: PropertyValueType.Number },
+    { path: 'y', label: 'Top', group: 'Placement', valueType: PropertyValueType.Number },
+    { path: 'width', label: 'Width', group: 'Placement', valueType: PropertyValueType.Number, constraints: { minimum: 0 } },
+    { path: 'height', label: 'Height', group: 'Placement', valueType: PropertyValueType.Number, constraints: { minimum: 0 } },
+];
+
+/**
+ * The editable properties of a screen template or dialog template itself.
+ */
+export const templateProperties: PropertyDescriptor[] = [
+    { path: 'displayName', label: 'Display name', group: 'General', valueType: PropertyValueType.String },
+    { path: 'description', label: 'Description', group: 'General', valueType: PropertyValueType.String },
+];

package/editing/layoutTypeEdits.ts

@@ -0,0 +1,135 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    ChangeLayoutTypeEdit, DiagnosticCode, FlowContainerKind, LayoutType, Orientation, SceneDiagnostic, SceneDocument,
+    SceneNodeKind,
+} from '@cratis/scene.model';
+import { errorDiagnostic, warningDiagnostic } from './diagnostics';
+import { findLayoutTypeDescriptor } from './DescriptorCatalog';
+import { getAtPath, mirroredPaths } from './documentPaths';
+import { EditSession } from './EditSession';
+import { cloneData } from './pathAccess';
+
+type Node = Record<string, unknown>;
+
+interface Conversion {
+    result: Node;
+
+    /** Properties that held a real value and are gone after the conversion. */
+    lost: string[];
+}
+
+const flowKinds: Partial<Record<LayoutType, FlowContainerKind>> = {
+    [LayoutType.FlowRow]: FlowContainerKind.Row,
+    [LayoutType.FlowColumn]: FlowContainerKind.Column,
+    [LayoutType.FlowGrid]: FlowContainerKind.Grid,
+};
+
+const panelOwnProperties: Partial<Record<LayoutType, string[]>> = {
+    [LayoutType.StackPanel]: ['orientation', 'spacing'],
+    [LayoutType.WrapPanel]: ['orientation', 'itemWidth', 'itemHeight'],
+    [LayoutType.DockPanel]: ['lastChildFill'],
+};
+
+const allPanelOwn = ['orientation', 'spacing', 'itemWidth', 'itemHeight', 'lastChildFill'];
+
+function isSet(node: Node, property: string): boolean {
+    return node[property] !== undefined && !(property === 'spacing' && node[property] === 0);
+}
+
+function convertFlow(source: Node, to: LayoutType): Conversion {
+    const result = cloneData(source);
+    const lost: string[] = [];
+    const target = flowKinds[to]!;
+
+    if (source.kind === FlowContainerKind.Grid && target !== FlowContainerKind.Grid) {
+        for (const property of ['columns', 'rows']) {
+            if (source[property] !== undefined) lost.push(property);
+            delete result[property];
+        }
+
+        const spans = (result.children as Node[]).filter(child => child.span !== undefined);
+        if (spans.length > 0) lost.push('span (on children)');
+        for (const child of spans) delete child.span;
+    }
+
+    result.kind = target;
+    return { result, lost };
+}
+
+function convertPanel(source: Node, to: LayoutType): Conversion {
+    const result = cloneData(source);
+    const keep = panelOwnProperties[to] ?? [];
+    const lost = allPanelOwn.filter(property => !keep.includes(property) && isSet(source, property));
+    for (const property of allPanelOwn.filter(candidate => !keep.includes(candidate))) delete result[property];
+
+    if (to === LayoutType.StackPanel) {
+        result.orientation ??= Orientation.Vertical;
+        result.spacing ??= 0;
+    } else if (to === LayoutType.WrapPanel) {
+        result.orientation ??= Orientation.Horizontal;
+    } else {
+        result.lastChildFill ??= true;
+    }
+
+    return { result, lost };
+}
+
+/**
+ * Applies a layout type change to a copy of the document.
+ *
+ * A change must be one the layout type allows. Changes that keep everything - row to column, a dock panel to a
+ * stack panel - go ahead. Changes that would drop real values, such as a grid's columns and spans when it becomes a
+ * row, are refused with the list of what would be lost unless the edit accepts the loss, and then go ahead with a
+ * warning that lists the same.
+ */
+export function applyChangeLayoutType(session: EditSession, edit: ChangeLayoutTypeEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const record = session.index.nodes.get(edit.nodeId);
+    if (!record) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.UnknownNode, `There is no node '${edit.nodeId}'.`, { nodeId: edit.nodeId }));
+        return;
+    }
+
+    if (record.kind !== SceneNodeKind.FlowNode && record.kind !== SceneNodeKind.Element) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.NotALayoutNode, `'${record.label}' is not a layout node.`, { nodeId: edit.nodeId }));
+        return;
+    }
+
+    if (!session.isLocal(record)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.NodeNotEditable, `'${edit.nodeId}' is inherited from '${session.sourceOf(record)}' and cannot be changed here.`, { nodeId: edit.nodeId }));
+        return;
+    }
+
+    const descriptor = findLayoutTypeDescriptor(session.context.catalog, record.typeId);
+    if (!descriptor) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.NotALayoutNode, `'${record.label}' is not a layout node.`, { nodeId: edit.nodeId }));
+        return;
+    }
+
+    if (!descriptor.capabilities.convertibleTo.includes(edit.to as LayoutType)) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.LayoutTypeNotConvertible, `A ${descriptor.label.toLowerCase()} cannot be changed into '${edit.to}'.`, { nodeId: edit.nodeId }));
+        return;
+    }
+
+    const isFlow = record.kind === SceneNodeKind.FlowNode;
+    const conversion = isFlow ? convertFlow(record.value as Node, edit.to as LayoutType) : convertPanel(record.value as Node, edit.to as LayoutType);
+
+    if (conversion.lost.length > 0) {
+        const lost = conversion.lost.join(', ');
+        if (!edit.acceptLoss) {
+            diagnostics.push(errorDiagnostic(
+                DiagnosticCode.LossyConversionNotAccepted,
+                `Changing to '${edit.to}' would drop ${lost}. Accept the loss to go ahead.`,
+                { nodeId: edit.nodeId }));
+            return;
+        }
+
+        diagnostics.push(warningDiagnostic(DiagnosticCode.LossyConversion, `Changed to '${edit.to}'; dropped ${lost}.`, { nodeId: edit.nodeId }));
+    }
+
+    for (const path of mirroredPaths(record.mirror, record.path)) {
+        const holder = getAtPath(clone, path.slice(0, -1)) as Record<string | number, unknown>;
+        holder[path[path.length - 1]] = cloneData(conversion.result);
+    }
+}

package/editing/nodeIds.ts

@@ -0,0 +1,111 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { EditingScope, EditingScopeKind } from '@cratis/scene.model';
+
+const separator = '#';
+
+function child(parentId: string, segment: string): string {
+    return [parentId, segment].join(separator);
+}
+
+/**
+ * The id of a layout node.
+ */
+export function layoutNodeId(name: string): string {
+    return `layout:${name}`;
+}
+
+/**
+ * The id of a screen template node.
+ */
+export function screenTemplateNodeId(name: string): string {
+    return `screenTemplate:${name}`;
+}
+
+/**
+ * The id of a dialog template node.
+ */
+export function dialogTemplateNodeId(name: string): string {
+    return `dialogTemplate:${name}`;
+}
+
+/**
+ * The id of a screen node.
+ */
+export function screenNodeId(name: string): string {
+    return `screen:${name}`;
+}
+
+/**
+ * The id of a named slot of a layout, template or screen.
+ */
+export function slotNodeId(ownerNodeId: string, slotName: string): string {
+    return child(ownerNodeId, `slot:${slotName}`);
+}
+
+/**
+ * The id of an element. Element ids are unique across a document and survive moves, so this is the stable way to
+ * address a component an author has placed.
+ */
+export function elementNodeId(elementId: string): string {
+    return `element:${elementId}`;
+}
+
+/**
+ * The id of the arrangement a layout, template or dialog positions its own slots with.
+ */
+export function ownerArrangementId(ownerNodeId: string): string {
+    return child(ownerNodeId, 'arrangement');
+}
+
+/**
+ * The id of a node of a flow arrangement.
+ *
+ * `holderId` is the slot or owner arrangement the flow belongs to, `variant` is `root` or `override<n>`, and
+ * `indexPath` walks down from that variant's root through each container's children. A flow node has no identity
+ * of its own, so the id is a structural address and only names the same node until the tree around it changes -
+ * read it from the same revision of the document you act on.
+ */
+export function flowNodeId(holderId: string, variant: string, indexPath: number[]): string {
+    return child(holderId, `flow:${[variant, ...indexPath].join('.')}`);
+}
+
+/**
+ * The id of a freeform arrangement.
+ */
+export function freeformNodeId(holderId: string): string {
+    return child(holderId, 'freeform');
+}
+
+/**
+ * The id of one placement within a freeform variant. `key` is the placed element's id, or the placed slot's name.
+ */
+export function placementNodeId(holderId: string, variantIndex: number, key: string): string {
+    return child(`${freeformNodeId(holderId)}:${variantIndex}`, `placement:${key}`);
+}
+
+/**
+ * The node id of the thing an editing scope names.
+ */
+export function scopeNodeId(scope: EditingScope): string {
+    switch (scope.kind) {
+        case EditingScopeKind.Screen: return screenNodeId(scope.name);
+        case EditingScopeKind.ScreenTemplate: return screenTemplateNodeId(scope.name);
+        case EditingScopeKind.DialogTemplate: return dialogTemplateNodeId(scope.name);
+        default: return layoutNodeId(scope.name);
+    }
+}
+
+/**
+ * The instance id an editing scope contributes under: `screen:<name>`, `template:<name>`, `dialog:<name>` or
+ * `layout:<name>`. It is what an {@link InstanceContribution} is keyed by.
+ */
+export function scopeInstanceId(scope: EditingScope): string {
+    switch (scope.kind) {
+        case EditingScopeKind.Screen: return `screen:${scope.name}`;
+        case EditingScopeKind.ScreenTemplate: return `template:${scope.name}`;
+        case EditingScopeKind.DialogTemplate: return `dialog:${scope.name}`;
+        default: return `layout:${scope.name}`;
+    }
+}

package/editing/pathAccess.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Reads a value at a dotted path in a plain object - `a.b.c` reads `bag.a.b.c` - or `undefined` when any step is
+ * missing.
+ */
+export function getValueAtPath(bag: Record<string, unknown>, path: string): unknown {
+    let current: unknown = bag;
+    for (const key of path.split('.')) {
+        if (current === null || typeof current !== 'object') return undefined;
+        current = (current as Record<string, unknown>)[key];
+    }
+
+    return current;
+}
+
+/**
+ * Whether a dotted path holds a value.
+ */
+export function hasValueAtPath(bag: Record<string, unknown>, path: string): boolean {
+    return getValueAtPath(bag, path) !== undefined;
+}
+
+/**
+ * Sets a value at a dotted path, creating intermediate objects. Mutates `bag`: callers hold a copy.
+ */
+export function setValueAtPath(bag: Record<string, unknown>, path: string, value: unknown): void {
+    const keys = path.split('.');
+    let current = bag;
+    for (const key of keys.slice(0, -1)) {
+        const next = current[key];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) {
+            current[key] = {};
+        }
+
+        current = current[key] as Record<string, unknown>;
+    }
+
+    current[keys[keys.length - 1]] = value;
+}
+
+/**
+ * Removes the value at a dotted path, leaving intermediate objects in place. Mutates `bag`.
+ */
+export function removeValueAtPath(bag: Record<string, unknown>, path: string): void {
+    const keys = path.split('.');
+    let current: unknown = bag;
+    for (const key of keys.slice(0, -1)) {
+        if (current === null || typeof current !== 'object') return;
+        current = (current as Record<string, unknown>)[key];
+    }
+
+    if (current !== null && typeof current === 'object') {
+        delete (current as Record<string, unknown>)[keys[keys.length - 1]];
+    }
+}
+
+/**
+ * A copy of plain JSON-shaped data that shares nothing with the original.
+ */
+export function cloneData<T>(value: T): T {
+    return structuredClone(value);
+}
+
+/**
+ * Whether two plain values are structurally equal.
+ */
+export function dataEquals(left: unknown, right: unknown): boolean {
+    if (left === right) return true;
+    if (left === null || right === null || typeof left !== 'object' || typeof right !== 'object') return false;
+    if (Array.isArray(left) !== Array.isArray(right)) return false;
+
+    const leftKeys = Object.keys(left as object);
+    const rightKeys = Object.keys(right as object);
+    if (leftKeys.length !== rightKeys.length) return false;
+
+    return leftKeys.every(key =>
+        Object.prototype.hasOwnProperty.call(right, key)
+        && dataEquals((left as Record<string, unknown>)[key], (right as Record<string, unknown>)[key]));
+}

package/editing/propertyEdits.ts

@@ -0,0 +1,119 @@
+// 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, PropertyValueType, QueryBinding, ResetPropertyEdit, SceneDiagnostic, SceneDocument,
+    SceneNodeKind, SetPropertyEdit,
+} from '@cratis/scene.model';
+import { describeNode } from './describeNode';
+import { errorDiagnostic } from './diagnostics';
+import { NodeRecord } from './DocumentIndex';
+import { getAtPath, mirroredPaths } from './documentPaths';
+import { EditSession } from './EditSession';
+import { cloneData, removeValueAtPath, setValueAtPath } from './pathAccess';
+import { validateBinding } from './validateBinding';
+import { validateValue } from './validateValue';
+
+/**
+ * Finds the node and descriptor an edit of a property addresses, or says why it cannot.
+ */
+export function resolveEditableProperty(
+    session: EditSession,
+    nodeId: string,
+    path: string,
+    diagnostics: SceneDiagnostic[],
+): { record: NodeRecord; descriptor: PropertyDescriptor } | 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)}'. An exposed property is configured with an instance edit, not by changing the node.`,
+            { nodeId, path }));
+        return undefined;
+    }
+
+    const description = describeNode(record, session.context.catalog);
+    const descriptor = description.properties.find(candidate => candidate.path === path);
+    if (!descriptor) {
+        diagnostics.push(errorDiagnostic(
+            description.diagnostics.length > 0 ? DiagnosticCode.MissingComponentDescriptor : DiagnosticCode.UnknownProperty,
+            description.diagnostics[0]?.message ?? `'${record.typeId}' has no property '${path}'.`,
+            { nodeId, path }));
+        return undefined;
+    }
+
+    if (descriptor.readOnly) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.ReadOnlyProperty, `'${descriptor.label}' is read-only.`, { nodeId, path }));
+        return undefined;
+    }
+
+    return { record, descriptor };
+}
+
+/**
+ * Checks a value for a property, including a query binding against the host's candidates.
+ *
+ * @returns Whether the value is acceptable; the reasons are added to `diagnostics`.
+ */
+export function checkValue(session: EditSession, descriptor: PropertyDescriptor, value: unknown, context: { nodeId?: string; component?: string; instance?: string }, diagnostics: SceneDiagnostic[]): boolean {
+    const problem = validateValue(descriptor, value);
+    if (problem) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidValue, `'${descriptor.label}': ${problem}.`, { ...context, path: descriptor.path }));
+        return false;
+    }
+
+    const candidates = session.context.queryCandidates;
+    if (descriptor.valueType === PropertyValueType.QueryReference && candidates && typeof value === 'object' && value !== null) {
+        const binding = value as QueryBinding;
+        const problems = validateBinding(descriptor, candidates.find(candidate => candidate.id === binding.queryId), binding);
+        diagnostics.push(...problems.map(problemDiagnostic => ({ ...problemDiagnostic, ...context })));
+        return problems.length === 0;
+    }
+
+    return true;
+}
+
+function bagFor(root: SceneDocument, record: NodeRecord, path: string[]): Record<string, unknown> | undefined {
+    const target = getAtPath(root, path) as Record<string, unknown> | undefined;
+    if (!target) return undefined;
+    const isComponent = record.kind === SceneNodeKind.Element && target.componentName !== undefined;
+    if (!isComponent) return target;
+    return (target.properties ??= {}) as Record<string, unknown>;
+}
+
+/**
+ * Applies a property set to a copy of the document.
+ */
+export function applySetProperty(session: EditSession, edit: SetPropertyEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveEditableProperty(session, edit.nodeId, edit.path, diagnostics);
+    if (!resolved) return;
+    if (!checkValue(session, resolved.descriptor, edit.value, { nodeId: edit.nodeId }, diagnostics)) return;
+
+    for (const path of mirroredPaths(resolved.record.mirror, resolved.record.path)) {
+        const bag = bagFor(clone, resolved.record, path as string[]);
+        if (bag) setValueAtPath(bag, edit.path, cloneData(edit.value));
+    }
+}
+
+/**
+ * Applies a property reset to a copy of the document.
+ */
+export function applyResetProperty(session: EditSession, edit: ResetPropertyEdit, clone: SceneDocument, diagnostics: SceneDiagnostic[]): void {
+    const resolved = resolveEditableProperty(session, edit.nodeId, edit.path, diagnostics);
+    if (!resolved) return;
+
+    if (resolved.descriptor.constraints?.required && resolved.descriptor.default === undefined) {
+        diagnostics.push(errorDiagnostic(DiagnosticCode.InvalidValue, `'${resolved.descriptor.label}' is required and has no default to go back to.`, { nodeId: edit.nodeId, path: edit.path }));
+        return;
+    }
+
+    for (const path of mirroredPaths(resolved.record.mirror, resolved.record.path)) {
+        const bag = bagFor(clone, resolved.record, path as string[]);
+        if (bag) removeValueAtPath(bag, edit.path);
+    }
+}