Add nodes that ask whether an animation still runs (#233)

A graph could start, pause and stop an animation and hear it finish,
but it could not ask in between whether one runs or how far it is.
Two data nodes answer that now.

- Animation playing takes an object and an animation and gives
  playing, progress and time left (s). It answers at the moment it is
  read: right after Play animation in the same pass it says on, and in
  the frame On animation finished fires it says off.
- With Animation at None it answers for the running animation started
  last on the object.
- Animation length gives the seconds of one pass, from the timeline
  and the frame rate alone.
- The rule is a pure function in src/core/model/animation.ts
  (playerStatus, leadingPlayer). The nodes reach an animation's
  length through a new field animation on GraphLookup.
- animationPort is exported so both nodes show the same picker as
  Play animation.

Decided in the issue: a Once (reset) counts as running while it blends
out, and progress and time left also hold for Loop and Ping-pong, at
the place of the playhead. On Ping-pong progress falls again on the
way back and time left counts to the next turn.

Decided here, the issue says nothing on it:
- A paused animation does not count as running. Progress and time
  left stand still.
- One that Stop animation fades out does not count as running, and
  its time left is 0.
- Time left of a Once (reset) includes its blend out. While it blends
  out progress is 1 and time left is the rest of the fade.

Finding, not fixed: on the node the name of the chosen animation
overlaps the output label progress in the same row. That comes from
the fixed node width in NodeView and was seen in the Fit view only.

Tests:
- Gate: 198 files, 2903 tests (2891 + 12), exit 0
- e2e 1-6: 282 checks passed, 06 has +2 for block 6z-ix
- Nine unit counter-probes fail, 1 to 4 tests each
- The browser counter-probe fails 6z-ix with ["false","false"]
- e2e total 1615 is computed, not measured in a full run. The smokes
  were not run.

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

tests/core/animation.test.ts

@@ -30,13 +30,20 @@ import { SetOverrideCommand } from '../../src/core/commands/sceneObjectCommands'
 import { RenameVariableCommand, SetVariablePrivateCommand } from '../../src/core/commands/variableCommands';
 import {
   animatableDefs,
+  type AnimationClip,
   animationDuration,
+  type AnimationPlayer,
   frameCount,
   isPositionRow,
+  leadingPlayer,
+  NOT_PLAYING,
   offeredDefs,
   pauseAnimation,
   PLACED_ROOT_ID,
   playAnimation,
+  type Playback,
+  playerStatus,
+  type PlayerStatus,
   playheadAt,
   stopAnimation,
   targetDefs,
@@ -46,6 +53,7 @@ import {
 } from '../../src/core/model/animation';
 import { SHADER_KEY, SHADER_PROPERTY } from '../../src/core/properties/shaders';
 import { previewHolder } from '../../src/core/model/animationPreview';
+import { graphLookup } from '../../src/core/model/graphLookup';
 import type {
   AnimationAsset,
   AnimationKey,
@@ -1382,6 +1390,149 @@ describe('the animation nodes', () => {
   });
 });
 
+describe('asking whether an animation still runs (#233)', () => {
+  const clip = (playback: Playback): AnimationClip => ({ frames: 10, fps: 10, playback });
+  const at = (time: number, more = {}): AnimationPlayer => ({
+    animationId: 'a',
+    time,
+    playing: true,
+    order: 1,
+    ...more,
+  });
+  const close = (status: PlayerStatus, progress: number, timeLeft: number) => {
+    expect(status.progress).toBeCloseTo(progress, 4);
+    expect(status.timeLeft).toBeCloseTo(timeLeft, 4);
+  };
+  /** What the node answers for the object, the lookup being the project's own. */
+  const asked = (f: SceneFixture, holder: { animations?: AnimationPlayer[] }, animationId: string) => {
+    const player = leadingPlayer(holder, animationId);
+    const known = player && graphLookup(f.project).animation(player.animationId);
+    return known ? playerStatus(known, player) : NOT_PLAYING;
+  };
+
+  it('says where the playhead stands in its pass, in every playback', () => {
+    close(playerStatus(clip('once'), at(0.25)), 0.25, 0.75);
+    close(playerStatus(clip('loop'), at(1.25)), 0.25, 0.75);
+    // Ping-pong turns on the last key: 9 frames up, and on the way back the progress falls again.
+    close(playerStatus(clip('pingpong'), at(0.3)), 1 / 3, 0.6);
+    close(playerStatus(clip('pingpong'), at(1.2)), 2 / 3, 0.6);
+    close(playerStatus(clip('once-reset'), at(0.25, { blendOut: 0.4 })), 0.25, 1.15);
+    close(playerStatus(clip('once'), at(0.25, { blendOut: 0.4 })), 0.25, 0.75);
+    expect(playerStatus({ frames: 0, fps: 10, playback: 'loop' }, at(3))).toEqual({
+      playing: true,
+      progress: 0,
+      timeLeft: 0,
+    });
+  });
+
+  it('still runs while a once-reset pass blends out, and is gone after', () => {
+    const { f, walk, sprite, frame } = slide({ playback: 'once-reset' });
+    expect(asked(f, sprite, walk.id)).toEqual(NOT_PLAYING);
+    playAnimation(sprite, walk.id, 0, 0.4);
+    for (let i = 0; i < 6; i++) frame(0.1);
+    expect(asked(f, sprite, walk.id).playing).toBe(true);
+    close(asked(f, sprite, walk.id), 0.5, 0.9);
+    for (let i = 0; i < 5; i++) frame(0.1);
+    expect(asked(f, sprite, walk.id).playing).toBe(true);
+    close(asked(f, sprite, walk.id), 1, 0.4);
+    frame(0.1);
+    close(asked(f, sprite, walk.id), 1, 0.3);
+    for (let i = 0; i < 3; i++) frame(0.1);
+    expect(asked(f, sprite, walk.id)).toEqual(NOT_PLAYING);
+  });
+
+  it('does not run paused or stopped, and keeps its place', () => {
+    const { f, walk, sprite, frame } = slide();
+    playAnimation(sprite, walk.id);
+    for (let i = 0; i < 4; i++) frame(0.1);
+    pauseAnimation(sprite, walk.id);
+    frame(0.5);
+    expect(asked(f, sprite, walk.id).playing).toBe(false);
+    close(asked(f, sprite, walk.id), 0.3, 0.7);
+    playAnimation(sprite, walk.id);
+    expect(asked(f, sprite, walk.id).playing).toBe(true);
+    stopAnimation(sprite, walk.id, 0.5);
+    expect(asked(f, sprite, walk.id).playing).toBe(false);
+    close(asked(f, sprite, walk.id), 0.3, 0);
+  });
+
+  it('answers for the one started last when no animation is named, a running one first', () => {
+    const { f, walk, sprite } = slide();
+    const bob = addAnimation(f, f.spriteId, { fps: 10 }, 'Bob');
+    playAnimation(sprite, walk.id);
+    playAnimation(sprite, bob.id);
+    expect(leadingPlayer(sprite, '')?.animationId).toBe(bob.id);
+    expect(leadingPlayer(sprite, walk.id)?.animationId).toBe(walk.id);
+    pauseAnimation(sprite, bob.id);
+    expect(leadingPlayer(sprite, '')?.animationId).toBe(walk.id);
+    pauseAnimation(sprite, walk.id);
+    expect(leadingPlayer(sprite, '')?.animationId).toBe(bob.id);
+    expect(asked(f, sprite, '').playing).toBe(false);
+    expect(leadingPlayer({}, '')).toBeUndefined();
+  });
+
+  /**
+   * A behavior below the sprite plays `walk` on its owner at start, and every frame writes down what
+   * `Animation playing` says: `ran` counts the frames it ran, `at` and `left` are the last answer.
+   */
+  function watching(playback: Playback, frames: number, named = true) {
+    const f = makeSpriteScene();
+    const box = place(f, f.spriteId, { x: 0, y: 0 });
+    const walk = addAnimation(f, f.spriteId, { fps: 10, playback });
+    addRow(f, walk, 'x', [
+      [0, 0],
+      [9, 90],
+    ]);
+    const behavior = makeBehavior(f, 'Logic', ['ran', 'at', 'left', 'length']);
+    place(f, behavior.id, { x: 0, y: 0 }, box);
+    const edit = graphEditor(f, behavior);
+    const start = edit.addNode('OnStart');
+    const owner = edit.addNode('Owner');
+    const play = edit.addNode('PlayAnimation', { animation: walk.id });
+    const update = edit.addNode('OnUpdate');
+    const playing = edit.addNode('AnimationPlaying', { animation: named ? walk.id : '' });
+    const length = edit.addNode('AnimationLength', { animation: walk.id });
+    const note = edit.variables(['at', 'left', 'length'], { write: true });
+    const branch = edit.addNode('Branch');
+    const count = edit.variables(['ran'], { write: true });
+    const add = edit.addNode('Add', { b: 1 });
+    edit.wire([
+      [start, 'exec', play, 'exec'],
+      [owner, 'object', play, 'object'],
+      [owner, 'object', playing, 'object'],
+      [play, 'exec', note, 'exec'],
+      [update, 'exec', note, 'exec'],
+      [playing, 'progress', note, 'at'],
+      [playing, 'timeLeft', note, 'left'],
+      [length, 'seconds', note, 'length'],
+      [note, 'exec', branch, 'exec'],
+      [playing, 'playing', branch, 'condition'],
+      [branch, 'then', count, 'exec'],
+      [count, 'ran', add, 'a'],
+      [add, 'result', count, 'ran'],
+    ]);
+    const { world, frame } = startWorld(f, { animations: true, behaviors: true });
+    for (let i = 0; i < frames; i++) frame(0.1);
+    return world.entities.find((e) => e.type === 'behavior')!.props;
+  }
+
+  it('answers in a graph: true in the very pulse that plays it, false once a once pass ended', () => {
+    // The start plays it and asks at once; the pass ends in frame 11, before the behaviors run.
+    expect(watching('once', 1).ran).toBe(2);
+    const midway = watching('once', 6);
+    expect(midway.ran).toBe(7);
+    expect(midway.at).toBeCloseTo(0.5, 4);
+    expect(midway.left).toBeCloseTo(0.5, 4);
+    expect(midway.length).toBe(1);
+    const over = watching('once', 20);
+    expect(over).toMatchObject({ ran: 11, at: 0, left: 0 });
+  });
+
+  it('answers for whatever runs on the object when the node names no animation', () => {
+    expect(watching('loop', 6, false)).toMatchObject({ ran: 7 });
+  });
+});
+
 describe('a row on z, the draw order', () => {
   /** The sprite placed twice: `box` at z 0 plays a row moving z 0 → 10, `wall` stands at z 5. */
   function climb() {

tests/core/node-catalog.test.ts

@@ -100,6 +100,23 @@ const at = (name: string, x: number, y: number) => ({ ...fakeEntity(name), x, y
 const emitTarget = fakeEntity('Sparks');
 /** Their own entity each: the animation nodes leave players on the object they are handed. */
 const dancer = fakeEntity('Dancer');
+/** An object whose once-reset "swing" has run out and blends back over half a second (#233). */
+const swinging = {
+  ...fakeEntity('Fighter'),
+  animations: [
+    {
+      animationId: 'swing',
+      time: 1,
+      playing: true,
+      order: 1,
+      fade: { seconds: 0.5, elapsed: 0, ended: true },
+    },
+  ],
+};
+const swingLookup: GraphLookup = {
+  ...NO_LOOKUP,
+  animation: (id) => (id === 'swing' ? { frames: 10, fps: 10, playback: 'once-reset' } : null),
+};
 const packed = fakeEntity('Player');
 const painted = fakeHandle({ width: 100, text: '' });
 
@@ -278,6 +295,41 @@ const CASES: Record<string, Case[]> = {
       outputs: { width: 0, height: 0 },
     },
   ],
+  AnimationPlaying: [
+    {
+      name: 'a once-reset pass blending out still runs, for as long as its blend out lasts (#233)',
+      inputs: { object: swinging, animation: 'swing' },
+      lookup: swingLookup,
+      outputs: { playing: true, progress: 1, timeLeft: 0.5 },
+    },
+    {
+      name: 'with no animation named answers for what runs on the object',
+      inputs: { object: swinging, animation: '' },
+      lookup: swingLookup,
+      outputs: { playing: true, progress: 1, timeLeft: 0.5 },
+    },
+    {
+      name: 'another animation is not playing',
+      inputs: { object: swinging, animation: 'walk' },
+      lookup: swingLookup,
+      outputs: { playing: false, progress: 0, timeLeft: 0 },
+    },
+    {
+      name: 'no object plays nothing',
+      inputs: { object: null, animation: '' },
+      lookup: swingLookup,
+      outputs: { playing: false, progress: 0, timeLeft: 0 },
+    },
+  ],
+  AnimationLength: [
+    {
+      name: 'one pass in seconds: ten frames at 10 fps',
+      inputs: { animation: 'swing' },
+      lookup: swingLookup,
+      outputs: { seconds: 1 },
+    },
+    { name: 'no animation is 0', inputs: { animation: '' }, outputs: { seconds: 0 } },
+  ],
   CurrentState: [
     {
       name: 'names the state the machine is in, and hands out its id as well',