Add React random pet actions

Author: FroeMic

apps/demo/src/main.tsx

@@ -1,6 +1,12 @@
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
-import { CODEX_PET_STATES, type CodexPetManifest, type CodexPetState } from "codex-pet-web";
+import {
+  CODEX_PET_STATES,
+  createCodexPetRandomActionRunner,
+  type CodexPetManifest,
+  type CodexPetSnapshot,
+  type CodexPetState
+} from "codex-pet-web";
 import { CodexPet, type CodexPetHandle } from "codex-pet-web-react";
 import "./styles.css";
 
@@ -28,7 +34,7 @@ function App() {
   const [pets, setPets] = useState<DemoPet[]>([]);
   const [selectedPetId, setSelectedPetId] = useState("");
   const [state, setState] = useState<CodexPetState>("idle");
-  const [scale, setScale] = useState(0.5);
+  const [scale, setScale] = useState(0.45);
   const [fps, setFps] = useState(8);
   const [paused, setPaused] = useState(false);
   const [reducedMotion, setReducedMotion] = useState(false);
@@ -59,6 +65,47 @@ function App() {
       });
   }, []);
 
+  useEffect(() => {
+    const runner = createCodexPetRandomActionRunner(
+      {
+        getSnapshot: () =>
+          petRef.current?.getSnapshot() ??
+          ({
+            id: "preview",
+            spritesheetUrl: "",
+            state: "idle",
+            baseState: "idle",
+            frame: 0,
+            scale,
+            fps,
+            position: null,
+            hidden: false,
+            mounted: false,
+            paused,
+            removed: false
+          } satisfies CodexPetSnapshot),
+        play: (nextState, options) => petRef.current?.play(nextState, options)
+      },
+      {
+        averageIntervalSeconds: 120,
+        minIntervalSeconds: 45,
+        maxIntervalSeconds: 300,
+        actions: [
+          { state: "waving", weight: 3 },
+          { state: "jumping", weight: 2 },
+          { state: "waiting", weight: 1 },
+          { state: "review", weight: 1 }
+        ]
+      }
+    );
+
+    runner.start();
+
+    return () => {
+      runner.destroy();
+    };
+  }, []);
+
   const selectedPet = useMemo(
     () => pets.find((pet) => pet.id === selectedPetId) ?? pets[0],
     [pets, selectedPetId]

apps/demo/test/defaults.test.ts

@@ -15,7 +15,7 @@ describe("demo defaults", () => {
   );
 
   it("starts pets at a compact size", () => {
-    expect(source).toContain("useState(0.5)");
+    expect(source).toContain("useState(0.45)");
   });
 
   it("keeps idle calmer while action states stay responsive", () => {
@@ -45,4 +45,10 @@ describe("demo defaults", () => {
     expect(localScript).toContain('"packages", "core", "example-pets"');
     expect(localScript).toContain('".codex", "pets"');
   });
+
+  it("runs occasional idle-only random actions", () => {
+    expect(source).toContain("createCodexPetRandomActionRunner");
+    expect(source).toContain("averageIntervalSeconds: 120");
+    expect(source).toContain('{ state: "waving", weight: 3 }');
+  });
 });

packages/react/src/index.ts

@@ -5,3 +5,4 @@ export {
   useCodexPet
 } from "./CodexPetProvider.js";
 export type { CodexPetProviderProps } from "./CodexPetProvider.js";
+export { useCodexPetRandomActions } from "./useCodexPetRandomActions.js";

packages/react/src/useCodexPetRandomActions.ts

@@ -0,0 +1,23 @@
+import {
+  createCodexPetRandomActionRunner,
+  type CodexPetId,
+  type CodexPetRandomActionRunnerOptions
+} from "codex-pet-web";
+import { useEffect } from "react";
+import { useCodexPet } from "./CodexPetProvider.js";
+
+export function useCodexPetRandomActions(
+  id: CodexPetId | undefined,
+  options: CodexPetRandomActionRunnerOptions
+): void {
+  const pet = useCodexPet(id);
+
+  useEffect(() => {
+    const runner = createCodexPetRandomActionRunner(pet, options);
+    runner.start();
+
+    return () => {
+      runner.destroy();
+    };
+  }, [pet, options]);
+}

packages/react/test/CodexPet.test.tsx

@@ -5,6 +5,7 @@ import {
   CodexPet,
   CodexPetProvider,
   useCodexPet,
+  useCodexPetRandomActions,
   type CodexPetHandle
 } from "../src/index";
 import type { CodexPetController, CodexPetManifest } from "codex-pet-web";
@@ -462,4 +463,41 @@ describe("CodexPet", () => {
 
     unmount();
   });
+
+  it("runs random provider actions through the React hook", () => {
+    function AmbientActions() {
+      useCodexPetRandomActions("assistant", {
+        averageIntervalSeconds: 120,
+        minIntervalSeconds: 45,
+        maxIntervalSeconds: 300,
+        actions: [{ state: "waving", weight: 1 }],
+        random: () => 0
+      });
+
+      return null;
+    }
+
+    const { host, unmount } = render(
+      <CodexPetProvider
+        pets={{
+          assistant: {
+            spritesheetUrl: "/pets/sapling/spritesheet.webp"
+          }
+        }}
+      >
+        <AmbientActions />
+        <CodexPet id="assistant" />
+      </CodexPetProvider>
+    );
+
+    const pet = host.querySelector("[data-codex-pet='assistant']") as HTMLDivElement;
+
+    act(() => {
+      vi.advanceTimersByTime(45_000);
+    });
+
+    expect(pet.style.backgroundPosition).toBe("0px -624px");
+
+    unmount();
+  });
 });