@lionweb/class-core 0.7.0-beta.9 → 0.7.0

package/src/deserializer.ts

@@ -16,12 +16,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import {
-    BuiltinPropertyValueDeserializer,
+    builtinPropertyValueDeserializer,
     Classifier,
     Containment,
     defaultSimplisticHandler,
     Enumeration,
-    Language,
     MemoisingSymbolTable,
     PrimitiveType,
     Property,
@@ -31,9 +30,10 @@ import {
     unresolved
 } from "@lionweb/core"
 import { LionWebId, LionWebJsonChunk, LionWebJsonNode } from "@lionweb/json"
-import { byIdMap } from "@lionweb/ts-utils"
+import { byIdMap, keepDefineds } from "@lionweb/ts-utils"
 
-import { DeltaHandler, IdMapping, ILanguageBase, INodeBase } from "./index.js"
+import { DeltaReceiver, IdMapping, ILanguageBase, INodeBase } from "./index.js"
+import { combinedLanguageBaseLookupFor } from "./factory.js"
 import { NodesToInstall } from "./linking.js"
 
 
@@ -43,26 +43,12 @@ import { NodesToInstall } from "./linking.js"
 export type Deserializer<T> = (
     serializationChunk: LionWebJsonChunk,
     dependentNodes?: INodeBase[],
+    idMapping?: IdMapping,
     propertyValueDeserializer?: PropertyValueDeserializer,
     problemHandler?: SimplisticHandler
 ) => T;
 
 
-const languageBaseLookupFor = (languageBases: ILanguageBase[]) =>
-    (language: Language) => {
-        const languageBase = languageBases.find((languageBase) => languageBase.language === language);
-        if (languageBase === undefined) {
-            throw new Error(`language ${language.name} (with key=${language.key} and version=${language.version}) not known`);
-        }
-        return languageBase;
-    };
-
-const factoryLookupFor = (languageBases: ILanguageBase[], handleDelta?: DeltaHandler) => {
-    const lookup = languageBaseLookupFor(languageBases);
-    return (language: Language) => lookup(language).factory(handleDelta);
-}
-
-
 /**
  * A quasi-tuple of the roots (of type {@link INodeBase}) of a model,
  * and its {@link IdMapping} instance.
@@ -73,24 +59,24 @@ export type RootsWithIdMapping = { roots: INodeBase[], idMapping: IdMapping };
 /**
  * @return a {@link Deserializer} function for the given languages (given as {@link ILanguageBase}s) that returns a {@link RootsWithIdMapping}.
  * @param languageBases the {@link ILanguageBase}s for (at least) all the languages used in the {@link LionWebJsonChunk} to deserialize, minus LionCore M3 and built-ins.
- * @param handleDelta an optional {@link DeltaHandler} that will be injected in all {@link INodeBase nodes} created.
+ * @param receiveDelta an optional {@link DeltaReceiver} that will be injected in all {@link INodeBase nodes} created.
  */
-export const nodeBaseDeserializerWithIdMapping = (languageBases: ILanguageBase[], handleDelta?: DeltaHandler): Deserializer<RootsWithIdMapping> => {
+export const nodeBaseDeserializerWithIdMapping = (languageBases: ILanguageBase[], receiveDelta?: DeltaReceiver): Deserializer<RootsWithIdMapping> => {
 
     const symbolTable = new MemoisingSymbolTable(languageBases.map(({language}) => language));
-    const languageBaseFor = languageBaseLookupFor(languageBases);
-    const factoryFor = factoryLookupFor(languageBases, handleDelta);
+    const languageBaseFor = combinedLanguageBaseLookupFor(languageBases);
 
     return (
-        serializationChunk: LionWebJsonChunk,
-        dependentNodes: INodeBase[] = [],
-        propertyValueDeserializer: PropertyValueDeserializer = new BuiltinPropertyValueDeserializer(),
-        problemsHandler: SimplisticHandler = defaultSimplisticHandler
+        serializationChunk,
+        dependentNodes = [],
+        idMapping,
+        propertyValueDeserializer = builtinPropertyValueDeserializer,
+        problemsHandler = defaultSimplisticHandler
     ): RootsWithIdMapping => {
 
         const nodesToInstall: NodesToInstall[] = [];
 
-        const createNode = ({id, classifier: classifierMetaPointer, properties, containments, references, annotations}: LionWebJsonNode) => {
+        const createNode = ({id, classifier: classifierMetaPointer, properties, containments, references, annotations}: LionWebJsonNode): (INodeBase | undefined) => {
             const languageMessage = `language ${classifierMetaPointer.language} (${classifierMetaPointer.version})`;
             const classifier = symbolTable.entityMatching(classifierMetaPointer);
             if (classifier === undefined || !(classifier instanceof Classifier)) {
@@ -98,7 +84,7 @@ export const nodeBaseDeserializerWithIdMapping = (languageBases: ILanguageBase[]
                 return undefined;
             }
 
-            const node = factoryFor(classifier.language)(classifier, id);
+            const node = languageBaseFor(classifier.language).factory(receiveDelta)(classifier, id);
 
             properties.forEach(({property: propertyMetaPointer, value}) => {
                 const feature = symbolTable.featureMatching(classifierMetaPointer, propertyMetaPointer);
@@ -152,15 +138,17 @@ export const nodeBaseDeserializerWithIdMapping = (languageBases: ILanguageBase[]
         };
 
         const nodesById = byIdMap(
-            serializationChunk.nodes
-                .map(createNode)
-                .filter((nodeOrUndef) => nodeOrUndef !== undefined) as INodeBase[]
+            keepDefineds(
+                serializationChunk
+                    .nodes
+                    .map(createNode)
+            )
         );
 
-        const dependentNodesById = byIdMap(dependentNodes)
+        const dependentNodesById = byIdMap(dependentNodes);
 
-        const lookupNodeById = (id: LionWebId) =>
-            nodesById[id] ?? dependentNodesById[id];
+        const lookupNodeById = (id: LionWebId): (INodeBase | undefined) =>
+            nodesById[id] ?? dependentNodesById[id] ?? idMapping?.tryFromId(id);
 
         nodesToInstall.forEach(([node, feature, ids]) => {
             if (feature instanceof Containment) {
@@ -217,16 +205,17 @@ export const nodeBaseDeserializerWithIdMapping = (languageBases: ILanguageBase[]
 /**
  * @return a {@link Deserializer} function for the languages (given as {@link ILanguageBase}s) that returns the roots (of type {@link INodeBase}) of the deserialized model.
  * @param languageBases the {@link ILanguageBase}s for (at least) all the languages used in the {@link LionWebJsonChunk} to deserialize, minus LionCore M3 and built-ins.
- * @param handleDelta an optional {@link DeltaHandler} that will be injected in all {@link INodeBase nodes} created.
+ * @param receiveDelta an optional {@link DeltaReceiver} that will be injected in all {@link INodeBase nodes} created.
  */
-export const nodeBaseDeserializer = (languageBases: ILanguageBase[], handleDelta?: DeltaHandler): Deserializer<INodeBase[]> => {
-    const deserializerWithIdMapping = nodeBaseDeserializerWithIdMapping(languageBases, handleDelta);
+export const nodeBaseDeserializer = (languageBases: ILanguageBase[], receiveDelta?: DeltaReceiver): Deserializer<INodeBase[]> => {
+    const deserializerWithIdMapping = nodeBaseDeserializerWithIdMapping(languageBases, receiveDelta);
     return (
-        serializationChunk: LionWebJsonChunk,
-        dependentNodes: INodeBase[] = [],
-        propertyValueDeserializer: PropertyValueDeserializer = new BuiltinPropertyValueDeserializer(),
-        problemsHandler: SimplisticHandler = defaultSimplisticHandler
+        serializationChunk,
+        dependentNodes,
+        idMapping,
+        propertyValueDeserializer = builtinPropertyValueDeserializer,
+        problemsHandler = defaultSimplisticHandler
     ): INodeBase[] =>
-        deserializerWithIdMapping(serializationChunk, dependentNodes, propertyValueDeserializer, problemsHandler).roots
+        deserializerWithIdMapping(serializationChunk, dependentNodes, idMapping, propertyValueDeserializer, problemsHandler).roots
 }
 

package/src/duplicator.ts

@@ -15,7 +15,7 @@
 // SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
 // SPDX-License-Identifier: Apache-2.0
 
-import {  Containment, Feature, idOf, Link, Property, Reference, SingleRef, unresolved } from "@lionweb/core"
+import { Containment, Feature, idOf, Link, Property, Reference, SingleRef, unresolved } from "@lionweb/core"
 import { LionWebId } from "@lionweb/json"
 import { asArray } from "@lionweb/ts-utils"
 

package/src/factory.ts

@@ -15,35 +15,49 @@
 // SPDX-FileCopyrightText: 2025 TRUMPF Laser SE and other contributors
 // SPDX-License-Identifier: Apache-2.0
 
+import { Language } from "@lionweb/core"
 import { lazyMapGet } from "@lionweb/ts-utils"
 import { ILanguageBase, NodeBaseFactory } from "./base-types.js"
-import { DeltaHandler } from "./deltas/index.js"
+import { DeltaReceiver } from "./deltas/index.js"
+
 
 /**
- * @return a {@link NodeBaseFactory factory function} that works for all given {@link ILanguageBase language bases}.
+ * @return a function that looks up the {@link ILanguageBase language base} for the {@link Language language} passed to it,
+ * from among the given language bases.
+ * The returned function throws when the language wasn't among the languages the given bases were for.
+ * The lookup is hashmap-backed, so efficient.
  */
-export const combinedFactoryFor = (languageBases: ILanguageBase[], handleDelta?: DeltaHandler): NodeBaseFactory => {
+export const combinedLanguageBaseLookupFor = (languageBases: ILanguageBase[]): ((language: Language) => ILanguageBase) => {
     // create lookup map:
-    const languageKey2version2factory: { [key: string]: { [version: string]: NodeBaseFactory } } = {}
+    const languageKey2version2base: { [key: string]: { [version: string]: ILanguageBase } } = {}
     languageBases.forEach((languageBase) => {
         const {key, version} = languageBase.language
-        const version2factory = lazyMapGet(languageKey2version2factory, key, () => ({}))
-        lazyMapGet(version2factory, version, () => languageBase.factory(handleDelta))
-            // (Note: don't destructure factory from languageBase, as that will unbind it as "this"!)
+        const version2base = lazyMapGet(languageKey2version2base, key, () => ({}))
+        lazyMapGet(version2base, version, () => languageBase)
     })
 
-    return (classifier, id) => {
-        const {key, version, name} = classifier.language
-        const version2factory = languageKey2version2factory[key]
-        if (version2factory === undefined) {
-            throw new Error(`language ${name} with key=${key} not known`)
+    return (language) => {
+        const {key, version, name} = language
+        const version2base = languageKey2version2base[key]
+        if (version2base === undefined) {
+            throw new Error(`language ${name} with key=${key} not registered`)
         }
-        const factory = version2factory[version]
-        if (factory === undefined) {
-            const candidateVersions = Object.keys(version2factory)
-            throw new Error(`language ${name} with key=${key} and version=${version} not known${candidateVersions.length > 0 ? `- candidate version${candidateVersions.length > 1 ? `s` : ``}: ${candidateVersions.join(", ")}` : ``}`)
+        const base = version2base[version]
+        if (base === undefined) {
+            const candidateVersions = Object.keys(version2base)
+            throw new Error(`language ${name} with key=${key} and version=${version} not registered${candidateVersions.length > 0 ? `- candidate version${candidateVersions.length > 1 ? `s` : ``}: ${candidateVersions.join(", ")}` : ``}`)
         }
-        return factory(classifier, id)
+        return base
     }
 }
 
+
+/**
+ * @return a {@link NodeBaseFactory factory function} that works for all given {@link ILanguageBase language bases}.
+ */
+export const combinedFactoryFor = (languageBases: ILanguageBase[], receiveDelta?: DeltaReceiver): NodeBaseFactory => {
+    const baseOf = combinedLanguageBaseLookupFor(languageBases)
+    return (classifier, id) =>
+        baseOf(classifier.language).factory(receiveDelta)(classifier, id)
+}
+

package/src/id-mapping.ts

@@ -20,6 +20,10 @@ import { LionWebId } from "@lionweb/json"
 
 import { INodeBase } from "./index.js"
 
+
+/**
+ * Type def. for a (hash-)map {@link LionWebId ID} → {@link INodeBase}.
+ */
 type NodesById = { [id: LionWebId]: INodeBase }
 
 
@@ -30,31 +34,65 @@ type NodesById = { [id: LionWebId]: INodeBase }
  */
 export class IdMapping {
 
-    nodesById: NodesById;
+    private nodesById: NodesById;
     constructor(nodesById: NodesById) {
         this.nodesById = {...nodesById};
     }
     // TODO  consider using an instance of Map<Id, INodeBase> instead
 
-    fromId(id: LionWebId): INodeBase {
+    /**
+     * @return the {@link INodeBase node} with the given {@link LionWebId `id`}, or
+     * @throws an Error if no node with the given ID was registered.
+     */
+    fromId = (id: LionWebId): INodeBase => {
         if (!(id in this.nodesById)) {
             throw new Error(`node with id=${id} not in ID mapping`);
         }
         return this.nodesById[id];
     }
 
+    /**
+     * @return the {@link INodeBase node} with the given {@link LionWebId `id`},
+     * or `undefined` if no node with the given ID was registered.
+     */
     tryFromId = (id: LionWebId): (INodeBase | undefined) =>
         this.nodesById[id];
 
+    /**
+     * @return the {@link INodeBase node} referenced from the given {@link LionWebId ID},
+     * or `unresolved` if `unresolved` was passed in or no node with the given ID was registered.
+     */
     fromRefId = (idOrUnresolved: IdOrUnresolved): SingleRef<INodeBase> =>
-        idOrUnresolved === null
-            ? null
+        idOrUnresolved === unresolved
+            ? unresolved
             : (this.nodesById[idOrUnresolved] ?? unresolved);
 
-    updateWith(node: INodeBase) {
+    /**
+     * Updates this {@link IdMapping} with the given `node` *and all its descendants* (recursively).
+     */
+    updateWith= (node: INodeBase) => {
         this.nodesById[node.id] = node;
         node.children   // recurse into all children
             .forEach((child) => this.updateWith(child));
+        // TODO  figure out when it's really necessary to call this, as it's potentially *very* expensive
+    }
+
+    /**
+     * Re-initializes this {@link IdMapping ID mapping} with the given nodes-by-ID.
+     * This completely removes all registrations of nodes,
+     * and should only be used by components which are in complete control of the nodes being passed to this method.
+     */
+    reinitializeWith = (nodesById: NodesById) => {
+        this.nodesById = nodesById;
+    }
+
+    /**
+     * Merges the given `that` {@link IdMapping} **in**to `this`.
+     */
+    mergeIn = (that: IdMapping) => {
+        for (const id in that.nodesById) {
+            this.nodesById[id] = that.nodesById[id];
+        }
     }
 
 }

package/src/textualizer.ts

@@ -54,7 +54,7 @@ export const asTreeTextWith = (identificationFor: (node: INodeBase) => string):
                 const valueManager = node.getPropertyValueManager(feature)
                 const displayValue = (() => {
                     if (!valueManager.isSet()) {
-                        return `$<not set>`
+                        return `<not set>`
                     }
                     const value = valueManager.getDirectly()
                     if (feature.type === LionCore_builtinsBase.INSTANCE.String) {

package/src/value-managers/annotations.ts

@@ -17,11 +17,12 @@
 
 import { action, observable } from "mobx"
 
-import { INodeBase, removeFromParent } from "../base-types.js"
+import { INodeBase } from "../base-types.js"
 import { checkIndex, ValueManager } from "./base.js"
 import {
     AnnotationAddedDelta,
     AnnotationDeletedDelta,
+    AnnotationMovedAndReplacedInSameParentDelta,
     AnnotationMovedFromOtherParentDelta,
     AnnotationMovedInSameParentDelta,
     AnnotationReplacedDelta
@@ -66,7 +67,7 @@ export class AnnotationsValueManager extends ValueManager {
             newAnnotation.attachTo(this.container, null);
             return false;
         } else {
-            const oldIndex = removeFromParent(oldParent, newAnnotation);
+            const oldIndex = oldParent.annotationsValueManager.removeDirectly(newAnnotation);
             newAnnotation.attachTo(this.container, null);
             return [oldParent, oldIndex];
         }
@@ -119,6 +120,31 @@ export class AnnotationsValueManager extends ValueManager {
         this.emitDelta(() => new AnnotationReplacedDelta(this.container, index, replacedAnnotation, newAnnotation));
     }
 
+    /**
+     * @return the moved and replaced annotations, as an array tuple.
+     */
+    @action moveAndReplaceAtIndexDirectly(oldIndex: number, newIndex: number): [INodeBase, INodeBase] | undefined {
+        checkIndex(oldIndex, this.annotations.length, false);
+        checkIndex(newIndex, this.annotations.length, false);
+        if (oldIndex !== newIndex) {
+            const movedAnnotation = this.annotations[oldIndex];
+            const replacedAnnotation = this.annotations[newIndex];
+            this.annotations[newIndex] = movedAnnotation;
+            this.annotations.splice(oldIndex, 1);
+            replacedAnnotation.detach();
+            return [movedAnnotation, replacedAnnotation];
+        }
+        return undefined;
+    }
+
+    @action moveAndReplaceAtIndex(oldIndex: number, newIndex: number) {
+        const participants = this.moveAndReplaceAtIndexDirectly(oldIndex, newIndex);
+        if (participants !== undefined) {
+            const [movedAnnotation, replacedAnnotation] = participants;
+            this.emitDelta(() => new AnnotationMovedAndReplacedInSameParentDelta(this.container, oldIndex, newIndex, replacedAnnotation, movedAnnotation));
+        }
+    }
+
     @action removeDirectly(annotationToRemove: INodeBase): number {
         const index = this.annotations.indexOf(annotationToRemove);
         if (index > -1) {

package/src/value-managers/base.ts

@@ -29,12 +29,12 @@ export abstract class ValueManager {
     }
 
     /**
-     * Emits a delta if a {@link DeltaHandler} is registered with the container.
-     * @param deltaThunk a thunk that generates the delta, and is only called when a delta handler is registered with the container.
+     * Emits a delta if a {@link DeltaReceiver} is registered with the container.
+     * @param deltaThunk a thunk that generates the delta, and is only called when a delta receiver is registered with the container.
      */
     emitDelta(deltaThunk: () => IDelta) {
-        if (this.container.handleDelta) {
-            this.container.handleDelta(deltaThunk());
+        if (this.container.receiveDelta) {
+            this.container.receiveDelta(deltaThunk());
         }
     }
 

package/src/value-managers/containments.ts

@@ -18,8 +18,18 @@
 import { Containment } from "@lionweb/core"
 import { action, observable } from "mobx"
 
-import { INodeBase, removeFromParent } from "../base-types.js"
-import { ChildAddedDelta, ChildDeletedDelta, ChildMovedDelta, ChildMovedInSameContainmentDelta, ChildReplacedDelta } from "../deltas/index.js"
+import { INodeBase } from "../base-types.js"
+import {
+    ChildAddedDelta,
+    ChildDeletedDelta,
+    ChildMovedAndReplacedFromOtherContainmentDelta,
+    ChildMovedAndReplacedFromOtherContainmentInSameParentDelta,
+    ChildMovedAndReplacedInSameContainmentDelta,
+    ChildMovedFromOtherContainmentDelta,
+    ChildMovedFromOtherContainmentInSameParentDelta,
+    ChildMovedInSameContainmentDelta,
+    ChildReplacedDelta
+} from "../deltas/index.js"
 import { checkIndex, FeatureValueManager } from "./base.js"
 
 
@@ -68,11 +78,47 @@ export abstract class SingleContainmentValueManager<T extends INodeBase> extends
     @action addDirectly(newChild: T) {
         const oldChild = this.getDirectly();
         if (oldChild !== undefined) {
-            throw new Error(`replacing a child using addDirectly on a value manager for a single-valued containment isn't allowed`);    // FIXME  unit test this
+            throw new Error(`replacing a child using addDirectly on a value manager for a single-valued containment isn't allowed`);    // TODO  unit test this
         }
         this.child.set(newChild);
     }
 
+    @action replaceWith(movedChild: T) {
+        const replacedChild = this.getDirectly();
+        if (replacedChild === undefined) {
+            // not a proper replace, but an add-set => delegate to regular setter (— unfortunately, through necessarily “unfolding the hierarchy”):
+            if (this instanceof OptionalSingleContainmentValueManager) {
+                this.set(movedChild);
+            }
+            if (this instanceof RequiredSingleContainmentValueManager) {
+                this.set(movedChild);
+            }
+        } else {
+            if (replacedChild === movedChild) {
+                // do nothing: nothing's changed
+            } else {
+                if (movedChild.parent === undefined) {
+                    this.emitDelta(() => new ChildReplacedDelta(this.container, this.feature, 0, replacedChild, movedChild));
+                } else {
+                    if (movedChild.parent === this.container) {
+                        if (movedChild.containment === this.containment) {
+                            this.emitDelta(() => new ChildMovedAndReplacedInSameContainmentDelta(this.container, this.containment, 0, 0, movedChild, replacedChild));
+                        } else {
+                            const oldIndex = removeFromContainment(replacedChild);
+                            this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentInSameParentDelta(this.container, movedChild.containment!, oldIndex, this.containment, 0, movedChild, replacedChild));
+                        }
+                    } else {
+                        const oldIndex = removeFromContainment(replacedChild);
+                        this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentDelta(this.container, this.containment, 0, movedChild, movedChild.parent!, movedChild.containment!, oldIndex, replacedChild));
+                    }
+                }
+                this.setDirectly(movedChild);
+                movedChild.attachTo(this.container, this.containment);
+                replacedChild.detach();
+            }
+        }
+    }
+
 }
 
 
@@ -95,8 +141,8 @@ export class OptionalSingleContainmentValueManager<T extends INodeBase> extends
             } else {
                 if (newChild.parent && newChild.containment) {
                     const oldParent = newChild.parent;
-                    removeFromParent(oldParent, newChild);
-                    this.emitDelta(() => new ChildMovedDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
+                    removeFromContainment(newChild);
+                    this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
                 } else {
                     this.emitDelta(() => new ChildAddedDelta(this.container, this.feature, 0, newChild));
                 }
@@ -112,13 +158,14 @@ export class OptionalSingleContainmentValueManager<T extends INodeBase> extends
                 if (oldChild === newChild) {
                     // do nothing: nothing's changed
                 } else {
+                    // FIXME  this could emit 2 deltas where it should be a single ChildReplaced-delta
                     if (oldChild.parent && oldChild.containment && oldChild.parent === this.container && oldChild.containment === this.feature) {
                         // FIXME  oldChild.parent COULD be this.container
                         this.emitDelta(() => new ChildDeletedDelta(this.container, this.feature, 0, oldChild));
                     }
                     oldChild.detach();
                     if (newChild.parent && newChild.containment) {
-                        removeFromParent(newChild.parent, newChild);
+                        removeFromContainment(newChild);
                     }
                     this.setDirectly(newChild);
                     newChild.attachTo(this.container, this.feature);
@@ -154,8 +201,8 @@ export class RequiredSingleContainmentValueManager<T extends INodeBase> extends
             } else {
                 if (newChild.parent && newChild.containment) {
                     const oldParent = newChild.parent;
-                    removeFromParent(oldParent, newChild);
-                    this.emitDelta(() => new ChildMovedDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
+                    removeFromContainment(newChild);
+                    this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(oldParent, newChild.containment!, 0, this.container, this.feature, 0, newChild));
                 } else {
                     this.emitDelta(() => new ChildAddedDelta(this.container, this.feature, 0, newChild));
                 }
@@ -175,7 +222,7 @@ export class RequiredSingleContainmentValueManager<T extends INodeBase> extends
                     }
                     oldChild.detach();
                     if (newChild.parent && newChild.containment) {
-                        removeFromParent(newChild.parent, newChild);
+                        removeFromContainment(newChild);
                     }
                     this.setDirectly(newChild);
                     newChild.attachTo(this.container, this.feature);
@@ -222,21 +269,36 @@ export abstract class MultiContainmentValueManager<T extends INodeBase> extends
         this.children.splice(index, 0, newChild);
     }
 
-    @action insertAtIndex(newChild: T, index: number) {
-        this.insertAtIndexDirectly(newChild, index);
-        if (newChild.parent === undefined && newChild.containment === undefined) {
-            this.emitDelta(() => new ChildAddedDelta(this.container, this.containment, index, newChild));
+    @action insertAtIndex(newChild: T, newIndex: number) {
+        if (newChild.parent === undefined) {
+            this.insertAtIndexDirectly(newChild, newIndex);
+            newChild.attachTo(this.container, this.containment);
+            this.emitDelta(() => new ChildAddedDelta(this.container, this.containment, newIndex, newChild));
         } else {
-            const oldIndex = removeFromParent(newChild.parent, newChild);
-            this.emitDelta(() => new ChildMovedDelta(newChild.parent!, newChild.containment!, oldIndex, this.container, this.containment, index, newChild));
-            newChild.detach();
+            if (newChild.parent === this.container) {
+                if (newChild.containment === this.containment) {
+                    const oldIndex = this.children.indexOf(newChild);
+                    this.moveDirectly(oldIndex, newIndex);
+                    this.emitDelta(() => new ChildMovedInSameContainmentDelta(this.container, this.containment, oldIndex, newIndex, newChild));
+                } else {
+                    const oldIndex = removeFromContainment(newChild);
+                    checkIndex(newIndex, this.children.length, true);
+                    this.insertAtIndexDirectly(newChild, newIndex);
+                    this.emitDelta(() => new ChildMovedFromOtherContainmentInSameParentDelta(this.container, newChild.containment!, oldIndex, newChild, this.containment, newIndex));
+                    newChild.attachTo(this.container, this.containment);
+                }
+            } else {
+                const oldIndex = removeFromContainment(newChild);
+                this.insertAtIndexDirectly(newChild, newIndex);
+                this.emitDelta(() => new ChildMovedFromOtherContainmentDelta(newChild.parent!, newChild.containment!, oldIndex, this.container, this.containment, newIndex, newChild));
+                newChild.attachTo(this.container, this.containment);
+            }
         }
-        newChild.attachTo(this.container, this.containment);
     }
 
     @action removeDirectly(childToRemove: T): number {
         const children = this.getDirectly();
-        const index = children.findIndex((child) => child === childToRemove);
+        const index = children.indexOf(childToRemove);
         if (index > -1) {
             children.splice(index, 1);
             return index;
@@ -244,6 +306,11 @@ export abstract class MultiContainmentValueManager<T extends INodeBase> extends
         return -1;
     }
 
+    @action removeAtIndexDirectly(index: number) {
+        checkIndex(index, this.children.length, false);
+        this.getDirectly().splice(index, 1);
+    }
+
     @action moveDirectly(oldIndex: number, newIndex: number): T | undefined {
         checkIndex(oldIndex, this.children.length, false);
         checkIndex(newIndex, this.children.length, false);
@@ -262,6 +329,39 @@ export abstract class MultiContainmentValueManager<T extends INodeBase> extends
         }
     }
 
+    @action replaceAtIndex(movedChild: T, newIndex: number) {
+        checkIndex(newIndex, this.children.length, false);
+        if (movedChild.parent === undefined) {
+            throw new Error(`a child-to-move (id=${movedChild.id}) must already be contained`);
+        }
+        const replacedChild = this.children[newIndex];
+        if (replacedChild === movedChild) {
+            // do nothing: nothing's changed
+        } else {
+            this.children.splice(newIndex, 1, movedChild);
+            if (replacedChild.parent !== undefined) {
+                const oldValueManager = replacedChild.parent.getContainmentValueManager(replacedChild.containment!);
+                const oldIndex = oldValueManager instanceof SingleContainmentValueManager
+                    ? 0
+                    : (oldValueManager as MultiContainmentValueManager<INodeBase>).children.indexOf(replacedChild);
+                if (replacedChild.parent === movedChild.parent) {
+                    if (replacedChild.containment === movedChild.containment) {
+                        this.emitDelta(() => new ChildMovedAndReplacedInSameContainmentDelta(this.container, this.containment, oldIndex, newIndex, movedChild, replacedChild));
+                    } else {
+                        this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentInSameParentDelta(this.container, replacedChild.containment!, oldIndex, this.containment, newIndex, movedChild, replacedChild));
+                    }
+                } else {
+                    this.emitDelta(() => new ChildMovedAndReplacedFromOtherContainmentDelta(this.container, this.containment, newIndex, movedChild, movedChild.parent!, movedChild.containment!, oldIndex, replacedChild));
+                }
+                replacedChild.detach();
+            } else {
+                // not a move+replace, but a regular replace instead:
+                this.emitDelta(() => new ChildReplacedDelta(this.container, this.containment, newIndex, replacedChild, movedChild));
+            }
+            movedChild.attachTo(this.container, this.containment);
+        }
+    }
+
 }
 
 
@@ -274,7 +374,7 @@ export class OptionalMultiContainmentValueManager<T extends INodeBase> extends M
 
     @action remove(childToRemove: T) {
         const children = this.getDirectly();
-        const index = children.findIndex((child) => child === childToRemove);
+        const index = children.indexOf(childToRemove);
         if (index > -1) {
             children.splice(index, 1);
             childToRemove.detach();
@@ -302,7 +402,7 @@ export class RequiredMultiContainmentValueManager<T extends INodeBase> extends M
 
     @action remove(childToRemove: T) {
         const children = this.getDirectly();
-        const index = children.findIndex((child) => child === childToRemove);
+        const index = children.indexOf(childToRemove);
         if (index > -1) {
             if (children.length === 1) {
                 this.throwOnUnset();
@@ -315,3 +415,27 @@ export class RequiredMultiContainmentValueManager<T extends INodeBase> extends M
 
 }
 
+/**
+ * Removes the given child node from its containment, and returns the containment index it had before removal.
+ */
+const removeFromContainment = (child: INodeBase): number => {
+    if (child.parent === undefined) {
+        throw new Error(`can't remove an orphan from its parent`)
+    }
+    if (child.containment === undefined) {
+        throw new Error(`can't remove an orphan from its containing feature`)
+    }
+    if (child.containment === null) {
+        throw new Error(`can't remove an annotation`)
+    }
+    const valueManager = child.parent.getContainmentValueManager(child.containment)
+    if (valueManager instanceof SingleContainmentValueManager) {
+        valueManager.setDirectly(undefined)
+        return 0
+    } else if (valueManager instanceof MultiContainmentValueManager) {
+        return valueManager.removeDirectly(child)
+    } else {
+        throw new Error(`don't know how to remove a child that's contained through a value manager of type ${valueManager.constructor.name}`)
+    }
+}
+

package/src/value-managers/properties.ts

@@ -29,6 +29,7 @@ import { FeatureValueManager } from "./base.js"
 export abstract class PropertyValueManager<T> extends FeatureValueManager<Property> {
 
     private readonly observableValue: IObservableValue<T | undefined> = observable.box<T | undefined>(undefined, {deep: false});
+        // TODO  could replace T with a sum types of the exact types we know a property's value can have
 
     get property(): Property {
         return this.feature;