Support Next client usage

Author: FroeMic

CHANGELOG.md

@@ -6,6 +6,8 @@
 - Added React `CodexPetProvider`, `useCodexPet`, and `useCodexPetRandomActions`.
 - Added `hide`, `show`, and `remove` controller commands.
 - Added idle-only weighted random action runners with configurable average intervals.
+- Marked React entry points as client modules for Next.js App Router usage.
+- Fixed drag state flicker when unchanged controlled state props are reapplied.
 - Updated the demo to start slightly smaller and merge bundled examples with local pets.
 - Removed the old Vertical fixture from the repository.
 

README.md

@@ -27,6 +27,12 @@ Framework-neutral DOM usage:
 npm install codex-pet-web
 ```
 
+## Next.js
+
+Use `codex-pet-web-react` from a client component. The React package ships
+`"use client"` markers, while `codex-pet-web` stays framework-neutral for shared
+types, constants, and browser runtime utilities.
+
 ## Quick Start: React
 
 ```tsx

packages/core/src/registry.ts

@@ -153,9 +153,10 @@ class CodexPetControllerImpl implements CodexPetController {
 
   setConfig(config: Partial<CodexPetConfig>): void {
     this.assertNotRemoved();
+    const previousState = this.config.state ?? DEFAULT_STATE;
     this.config = { ...this.config, ...config };
 
-    if (config.state) {
+    if (config.state && config.state !== previousState) {
       this.baseState = config.state;
       this.state = config.state;
       this.animator?.setBaseState(config.state, { interrupt: true });

packages/core/test/registry.test.ts

@@ -144,4 +144,46 @@ describe("Codex pet registry", () => {
       position: { x: 100, y: 120 }
     });
   });
+
+  it("does not reset temporary drag state when unchanged config is applied", () => {
+    const registry = createCodexPetRegistry({
+      pets: {
+        assistant: {
+          spritesheetUrl: "/pets/sapling/spritesheet.webp",
+          state: "idle",
+          floating: true,
+          draggable: true
+        }
+      }
+    });
+    const assistant = registry.get("assistant");
+    const element = bind(assistant);
+
+    element.dispatchEvent(
+      new MouseEvent("pointerdown", {
+        bubbles: true,
+        button: 0,
+        clientX: 20,
+        clientY: 30
+      })
+    );
+    window.dispatchEvent(
+      new MouseEvent("pointermove", {
+        bubbles: true,
+        clientX: 40,
+        clientY: 30
+      })
+    );
+
+    expect(assistant.getSnapshot().state).toBe("running-right");
+
+    assistant.setConfig({
+      spritesheetUrl: "/pets/sapling/spritesheet.webp",
+      state: "idle",
+      floating: true,
+      draggable: true
+    });
+
+    expect(assistant.getSnapshot().state).toBe("running-right");
+  });
 });

packages/react/README.md

@@ -10,6 +10,35 @@ npm install codex-pet-web-react codex-pet-web
 
 `react` is a peer dependency.
 
+## Next.js
+
+`codex-pet-web-react` is client-only and ships `"use client"` markers. In a
+Next.js App Router app, import it from a client component and render that client
+component from your layout or page:
+
+```tsx
+"use client";
+
+import { CodexPet, CodexPetProvider } from "codex-pet-web-react";
+
+export function PetLayer() {
+  return (
+    <CodexPetProvider
+      pets={{
+        assistant: {
+          spritesheetUrl: "/codex-pets/sapling/spritesheet.webp",
+          scale: 0.45,
+          floating: { x: 24, y: 24 },
+          draggable: true
+        }
+      }}
+    >
+      <CodexPet id="assistant" />
+    </CodexPetProvider>
+  );
+}
+```
+
 ## Basic Usage
 
 ```tsx

packages/react/src/CodexPet.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createCodexPetRegistry,
   type CodexPetAnimationEvent,

packages/react/src/CodexPetProvider.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createCodexPetRegistry,
   type CodexPetConfig,

packages/react/src/index.ts

@@ -1,3 +1,5 @@
+"use client";
+
 export { CodexPet } from "./CodexPet.js";
 export type { CodexPetHandle, CodexPetProps } from "./CodexPet.js";
 export {

packages/react/src/useCodexPetRandomActions.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   createCodexPetRandomActionRunner,
   type CodexPetId,