fix #203: preserve animation on appearance updates

memory/project_animation_runtime.md

@@ -0,0 +1,29 @@
+# Animation Runtime Crib
+
+## Live entity lifecycle invariant
+
+`CreateObject` creates a live entity and a real `DeleteObject` destroys it.
+`ObjDescEvent (0xF625)` is neither: it changes appearance on the existing object.
+
+For an appearance update, preserve:
+
+- `WorldEntity` object identity and local `Id`
+- `AnimatedEntity`, `AnimationSequencer`, frame/range/rate state
+- movement-controller and animation-manager bindings
+- physics host, collision registration, dead reckoning, and selection state
+
+Replace only resolved `MeshRefs`, palette override, part overrides, and visual
+bounds, then invalidate the entity-classification cache. The paperdoll may clone
+the updated appearance separately.
+
+Retail oracle chain:
+
+`SmartBox::HandleObjDescEvent` → `SmartBox::UpdateVisualDesc` →
+`ACCObjectMaint::SetVisualDesc` →
+`CPhysicsObj::DoObjDescChangesFromDefault` →
+`CPartArray::DoObjDescChanges`.
+
+Regression history: treating `0xF625` as despawn/respawn severed the player
+controller from the active animation state, so unequipping armor froze character
+animation and made animation-dependent door interaction appear frozen. Fixed as
+issue #203 on 2026-07-11 and user-gated in a Release client.