Add an activity method to keep Jax awake

src/fallback/index.ts

@@ -218,6 +218,9 @@ export function createFallbackJax(host: HTMLElement, options: JaxOptions = {}):
     pet() {
       api.setMood('wave');
     },
+    activity() {
+      // The fallback has no idle moods, so there is nothing to wake or put off.
+    },
     setReducedMotion: (on) => {
       if (!disposed) setStill(on);
     },

src/motion/motion.test.ts

@@ -466,6 +466,38 @@ describe('moods', () => {
     expect(motion.mood).toBe('chill');
   });
 
+  it('wakes from a nap on activity, and puts the next nap off while there is some', () => {
+    const motion = engine({ autoIdle: true, random: () => 0.1 });
+    run(motion, 50, 60);
+    expect(motion.mood).toBe('nap');
+    motion.activity();
+    run(motion, 2, 60);
+    expect(motion.mood).not.toBe('nap');
+    // Regular activity keeps him from napping for far longer than the nap delay.
+    for (let i = 0; i < 100; i++) {
+      run(motion, 1, 30);
+      motion.activity();
+    }
+    expect(motion.mood).not.toBe('nap');
+  });
+
+  it('does not let activity change a mood the host is holding', () => {
+    const motion = engine({ autoIdle: true, random: () => 0 });
+    motion.setMood('writing');
+    for (let i = 0; i < 30; i++) {
+      run(motion, 2, 30);
+      motion.activity();
+    }
+    expect(motion.mood).toBe('writing');
+  });
+
+  it('ignores activity without autoIdle', () => {
+    const motion = engine();
+    motion.activity();
+    run(motion, 2, 30);
+    expect(motion.mood).toBe('chill');
+  });
+
   it('holds a host mood against the idle rotation', () => {
     const motion = engine({ autoIdle: true, random: () => 0 });
     motion.setMood('writing');

src/motion/motion.ts

@@ -264,6 +264,11 @@ export function createMotion(options: MotionEngineOptions): Motion {
       else machine.request(mood);
       syncLayers();
     },
+    activity() {
+      if (!autoIdle) return;
+      machine.activity();
+      syncLayers();
+    },
     pet() {
       if (machine.mood === 'wave' || pet) return;
       pet = { startedAt: timeSeconds };

src/render/createJax.test.ts

@@ -55,6 +55,7 @@ function makeMotion() {
     },
     setMood: vi.fn((m: Mood) => void (mood = m)),
     pet: vi.fn(),
+    activity: vi.fn(),
     setReducedMotion: vi.fn(),
     step: vi.fn((dt: number) => {
       dts.push(dt);
@@ -243,6 +244,10 @@ describe('createJax', () => {
     expect(renderer.render).toHaveBeenCalledTimes(2);
     expect(scheduler.pending).toBe(0);
 
+    // Activity reaches the motion, and draws a frame so a wake from a nap shows even when still.
+    jax.activity();
+    expect(motion.activity).toHaveBeenCalledTimes(1);
+
     query.set(false);
     expect(motion.setReducedMotion).toHaveBeenCalledWith(false);
     expect(scheduler.pending).toBe(1);

src/render/createJax.ts

@@ -224,6 +224,10 @@ export async function createJax(
       motion.pet();
       markChanged();
     },
+    activity() {
+      motion.activity();
+      markChanged();
+    },
     setReducedMotion(on) {
       if (on === reduced) return;
       reduced = on;

src/types.ts

@@ -196,6 +196,11 @@ export interface Jax {
   setMood(mood: Mood): void;
   /** A friendly wave, as if he were petted. */
   pet(): void;
+  /**
+   * Tell him something is happening in the app. With `autoIdle`, he wakes if he is napping and puts
+   * off the next nap and idle change, without changing a mood that is being held.
+   */
+  activity(): void;
   setReducedMotion(on: boolean): void;
   /** Stop, release the GPU and remove the canvas. Safe to call twice. */
   dispose(): void;
@@ -206,6 +211,8 @@ export interface Motion {
   readonly mood: Mood;
   setMood(mood: Mood): void;
   pet(): void;
+  /** Something happened in the app; see `Jax.activity`. */
+  activity(): void;
   setReducedMotion(on: boolean): void;
   /** Advance by `dt` seconds (clamped inside) and return the pose to draw now. */
   step(dt: number): Readonly<Pose>;