Animations blend out on Stop and at the end of Once (reset), and Play can restart a running animation (#106)

Stop animation gets a blend (s) port that fades the animation back to what
lies underneath. Play animation gets blend out (s) for Once (reset) and a
restart port that starts a running, paused or fading animation from frame 0.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/core/graph/nodes/action/animationNodes.ts

@@ -1,7 +1,7 @@
 import { pauseAnimation, playAnimation, stopAnimation } from '../../../model/animation';
 import type { NodeDef, PortDef } from '../../NodeRegistry';
-import { asEntity, asNumber, asString } from '../../values';
-import { exec, num, obj, withDefault } from '../shared';
+import { asBoolean, asEntity, asNumber, asString } from '../../values';
+import { bool, exec, num, obj, withDefault } from '../shared';
 
 /**
  * The `animation` input of the three animation nodes; unconnected it shows the animation picker, the
@@ -22,14 +22,31 @@ export const PlayAnimation: NodeDef = {
     'Plays an animation on an object: its rows reach the object and what is placed inside it, so every ' +
     'instance plays on its own. A paused one runs on from where it stands; one already running keeps its ' +
     'frame but wins again over the others on the object. Blend fades numbers and colours over that many ' +
-    'seconds from what they held when it took over; everything else switches at once.',
-  inputs: [exec(), obj('object'), animationPort(), withDefault(num('blend', 'blend (s)'), 0)],
+    'seconds from what they held when it took over; everything else switches at once. Blend out is for ' +
+    'Once (reset): when its frames run out it fades back to where it started over that many seconds. ' +
+    'Restart starts one already running or paused over from its first frame – blended in from where it ' +
+    'stands when Blend is set.',
+  inputs: [
+    exec(),
+    obj('object'),
+    animationPort(),
+    withDefault(num('blend', 'blend (s)'), 0),
+    withDefault(num('blendOut', 'blend out (s)'), 0),
+    withDefault(bool('restart'), false),
+  ],
   outputs: [exec()],
   params: [],
   run: (_ctx, inputs) => {
     const target = asEntity(inputs.object);
     const animation = asString(inputs.animation);
-    if (target && animation) playAnimation(target, animation, Math.max(0, asNumber(inputs.blend)));
+    if (target && animation)
+      playAnimation(
+        target,
+        animation,
+        Math.max(0, asNumber(inputs.blend)),
+        Math.max(0, asNumber(inputs.blendOut)),
+        asBoolean(inputs.restart),
+      );
     return { next: 'exec' };
   },
 };
@@ -39,13 +56,15 @@ export const StopAnimation: NodeDef = {
   label: 'Stop animation',
   category: 'action',
   description:
-    'Ends an animation on an object where it stands – the values it set stay. Leave Animation at None to end every one.',
-  inputs: [exec(), obj('object'), animationPort()],
+    'Ends an animation on an object where it stands – the values it set stay. With a blend it fades out ' +
+    'over that many seconds instead, back to what another animation sets there or else to what the ' +
+    'values were when it started. Leave Animation at None to end every one.',
+  inputs: [exec(), obj('object'), animationPort(), withDefault(num('blend', 'blend (s)'), 0)],
   outputs: [exec()],
   params: [],
   run: (_ctx, inputs) => {
     const target = asEntity(inputs.object);
-    if (target) stopAnimation(target, asString(inputs.animation));
+    if (target) stopAnimation(target, asString(inputs.animation), Math.max(0, asNumber(inputs.blend)));
     return { next: 'exec' };
   },
 };