neko-vue 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -2,19 +2,24 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
-## [0.1.6](https://github.com/AscaL/neko-vue/compare/v0.1.5...v0.1.6) (2026-04-05)
+## [0.1.7](https://github.com/AscaL/neko-vue/compare/v0.1.6...v0.1.7) (2026-04-06)
+
+### Features
 
+- add options for behavior tracking and display in Neko components ([43a72b0](https://github.com/AscaL/neko-vue/commit/43a72b007b6f9da81441cfb1955b4ad9a92a08ef))
+- implement NekoEngineMovement and viewport handling for enhanced pet behavior and movement logic ([2dd8484](https://github.com/AscaL/neko-vue/commit/2dd848413050e2e51bc7f6e215ed6c6f4bb05407))
+
+## [0.1.6](https://github.com/AscaL/neko-vue/compare/v0.1.5...v0.1.6) (2026-04-05)
 
 ### Features
 
-* add NekoEngineApi and NekoEngineState types for enhanced engine functionality ([138ca8d](https://github.com/AscaL/neko-vue/commit/138ca8d2486ec6e8ace114803db32bea0a14548b))
+- add NekoEngineApi and NekoEngineState types for enhanced engine functionality ([138ca8d](https://github.com/AscaL/neko-vue/commit/138ca8d2486ec6e8ace114803db32bea0a14548b))
 
 ## [0.1.5](https://github.com/AscaL/neko-vue/compare/v0.1.4...v0.1.5) (2026-04-04)
 
-
 ### Features
 
-* implement viewport clamping for Neko sprite and enhance resize handling with tests ([086d2ca](https://github.com/AscaL/neko-vue/commit/086d2caddc44afd1043c18c633b9ab02cf505598))
+- implement viewport clamping for Neko sprite and enhance resize handling with tests ([086d2ca](https://github.com/AscaL/neko-vue/commit/086d2caddc44afd1043c18c633b9ab02cf505598))
 
 ## [0.1.4](https://github.com/AscaL/neko-vue/compare/v0.1.3...v0.1.4) (2026-04-04)
 
@@ -22,11 +27,10 @@ All notable changes to this project will be documented in this file. See [commit
 
 ## [0.1.2](https://github.com/AscaL/neko-vue/compare/v0.1.1...v0.1.2) (2026-04-04)
 
-
 ### Features
 
-* add new behavior cycle types and utility functions to enhance behavior mode handling ([c5dd242](https://github.com/AscaL/neko-vue/commit/c5dd242d27164085865665521d79acd6b3fd8b89))
-* enhance NekoPet component with public props and improve behavior mode handling in runtime ([53ed755](https://github.com/AscaL/neko-vue/commit/53ed7553fea2078c5ff648c5753a87420eb76b32))
+- add new behavior cycle types and utility functions to enhance behavior mode handling ([c5dd242](https://github.com/AscaL/neko-vue/commit/c5dd242d27164085865665521d79acd6b3fd8b89))
+- enhance NekoPet component with public props and improve behavior mode handling in runtime ([53ed755](https://github.com/AscaL/neko-vue/commit/53ed7553fea2078c5ff648c5753a87420eb76b32))
 
 ## [0.1.1](https://github.com/AscaL/neko-vue/compare/v0.1.0...v0.1.1) (2026-04-04)
 

package/README.md

@@ -18,24 +18,24 @@ Vue 3 integration for a **viewport-fixed** desktop pet: **`NekoPet`**, **`useNek
 
 The **playground** is the canonical integration reference:
 
-| Route | File | Purpose |
-| ----- | ---- | ------- |
-| `/` | [`playground/src/DemoNekoPet.vue`](./playground/src/DemoNekoPet.vue) | `<NekoPet />`, exposed `instance`, HUD via [`useNekoHud.ts`](./playground/src/useNekoHud.ts) |
-| `/composable` | [`playground/src/DemoUseNekoAnchor.vue`](./playground/src/DemoUseNekoAnchor.vue) | `useNeko` + `anchorRef` / `useTemplateRef`, flags panel |
-| `/customize` | [`playground/src/DemoCustomize.vue`](./playground/src/DemoCustomize.vue) | Sandbox: placement, `behaviorCycle`, `cursorStandoffPx`, **Apply** |
+| Route         | File                                                                             | Purpose                                                                               |
+| ------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `/`           | [`playground/src/DemoNekoPet.vue`](./playground/src/DemoNekoPet.vue)             | `<NekoPet />`, `show-behavior-on-click`, `@behavior-mode-change`, HUD + last emit     |
+| `/composable` | [`playground/src/DemoUseNekoAnchor.vue`](./playground/src/DemoUseNekoAnchor.vue) | `useNeko` + anchor; toggles for `showBehaviorOnClick` / `onBehaviorModeChange` logger |
+| `/customize`  | [`playground/src/DemoCustomize.vue`](./playground/src/DemoCustomize.vue)         | Sandbox: placement, `behaviorCycle`, `cursorStandoffPx`, **Apply**                    |
 
 Routing: [`playground/src/router.ts`](./playground/src/router.ts). Shell UI: [`playground/src/App.vue`](./playground/src/App.vue), [`playground/src/PlaygroundLiveStats.vue`](./playground/src/PlaygroundLiveStats.vue).
 
 ### `NekoPet` vs `useNeko`
 
-| | Use when |
-| --- | --- |
-| **`NekoPet`** | Props only; anchor via **`anchor-selector`** (CSS string). |
-| **`useNeko`** | **`anchorRef`**, **`instance` / `isReady` / `error`**, **`setMode`**, **`destroy`**, **`petInteractionAwake`**, or options from **`computed()`**. |
+|               | Use when                                                                                                                                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`NekoPet`** | Props + **`@behavior-mode-change`**; optional **`show-behavior-on-click`** built-in label. Anchor via **`anchor-selector`** only (no template ref).                                                                          |
+| **`useNeko`** | **`anchorRef`**, **`instance` / `isReady` / `error`**, **`setMode`**, **`destroy`**, **`petInteractionAwake`**, plus all **`NekoOptions`** (e.g. **`onBehaviorModeChange`**, **`showBehaviorOnClick`**) in reactive options. |
 
 `NekoPet` forwards props into `useNeko` ([`src/vue/NekoPet.ts`](./src/vue/NekoPet.ts)); core logic: [`src/vue/useNeko.ts`](./src/vue/useNeko.ts).
 
-**Imports:** `import { NekoPet, useNeko, … } from "neko-vue"`. In templates, multi-word props use **kebab-case** (`start-corner`, `behavior-mode`, `behavior-cycle`, `cursor-standoff-px`, `anchor-selector`, `respect-reduced-motion`, `rest-until-first-pet-interaction`, …).
+**Imports:** `import { NekoPet, useNeko, … } from "neko-vue"`. In templates, multi-word props use **kebab-case** (`start-corner`, `behavior-mode`, `behavior-cycle`, `cursor-standoff-px`, `anchor-selector`, `respect-reduced-motion`, `rest-until-first-pet-interaction`, `show-behavior-on-click`, …). Listen for **`@behavior-mode-change`** on **`NekoPet`** for the new **`BehaviorMode`** after each click cycle.
 
 ---
 
@@ -43,10 +43,12 @@ Routing: [`playground/src/router.ts`](./playground/src/router.ts). Shell UI: [`p
 
 - **Pet is not in your DOM tree** — it is fixed to the viewport; “placement” is **`startX` / `startY`**, **`startCorner`**, **`anchorRef`** / **`anchorSelector`** (see [`src/placement/nekoPlacement.ts`](./src/placement/nekoPlacement.ts)).
 - **Per axis:** explicit coord → anchor top-left → corner → `0`. **`0`** is valid. Corner math uses **`NEKOJS_SPRITE_SIZE` (32)**.
-- **Anchor gate:** `createNeko` waits until the element exists and has **non-zero** size. **`ResizeObserver`** runs in **`useNeko`** only when **`anchorRef`** is set—not for **`anchorSelector`** alone.
+- **Viewport bounds:** Runtime [`readViewportBounds`](./src/runtime/nekoViewport.ts) uses **`visualViewport`** when it reports **positive** width and height (typical mobile chrome), otherwise **`document.documentElement.clientWidth`** and **`window.innerHeight`**. The pet loop runs on **`requestAnimationFrame`**; **`window`** **resize** and **`visualViewport`** **`resize`/`scroll`** are coalesced with rAF. On those layout updates, **`home`** and the sprite snap to **initial placement** clamped into the new bounds (all **`behaviorMode`** values, **`follow`** or **`rest`**).
+- **Anchor gate (`useNeko` / `NekoPet`):** If **`anchorRef`** or **`anchorSelector`** is set, creation is **deferred** until the resolved element exists and has **positive** layout size (`getBoundingClientRect` / `offsetWidth`×`offsetHeight`). Low-level **`createNeko()`** itself does not perform this wait—it appends the pet to **`document.body`** immediately. **`ResizeObserver`** (for recreate when the anchor box changes) runs in **`useNeko`** only when **`anchorRef`** is set, not for **`anchorSelector`** alone.
 - **`mode`:** **`follow`** (loop on) vs **`rest`** (stop at resolved home after create). Imperative: **`setMode`**, **`restAtOrigin`**, **`resumeFollow`**, or reactive **`mode`** in options. Changing placement-related options **recreates** the instance (no teleport API).
-- **`behaviorMode`:** **Initial** create (+ special cases leaving the first-click gate); **live** mode advances by **clicking the cat** (if **`allowBehaviorChange`**). On recreate, the **previous engine mode** is kept unless leaving that gate (`applyBehaviorModeForRecreate` in [`src/vue/useNeko.ts`](./src/vue/useNeko.ts)). Enum **`BehaviorMode`** (ids **0…6** in the engine), **`BEHAVIOR_MODES_IN_ORDER`**, **`DEFAULT_NEKO_BEHAVIOR_CYCLE`**, **`BehaviorCycle`**, **`isBehaviorMode`** — [`src/types/index.ts`](./src/types/index.ts). **Readable strings (HUD / logs / hovers):** **`formatBehaviorMode`**, **`behaviorModeEnumName`**, **`BEHAVIOR_MODE_LABELS`**. **Stable cycle typing** (avoid inferred `0 \| 2 \| 1` unions): **`behaviorCycleOf(BehaviorMode.ChaseMouse, …)`**. **`NekoPet`** is cast to **`DefineComponent<NekoPetPublicProps>`** so Volar shows **`BehaviorMode`** on props, not plain `number`. Custom click order: **`behaviorCycle`**; invalid ids stripped in [`normalizeBehaviorCycle`](./src/runtime/nekojsRuntime.ts).
+- **`behaviorMode`:** **Initial** create (+ special cases leaving the first-click gate); **live** mode advances by **clicking the cat** (if **`allowBehaviorChange`**). On recreate, the **previous engine mode** is kept unless leaving that gate (`applyBehaviorModeForRecreate` in [`src/vue/useNeko.ts`](./src/vue/useNeko.ts)). Enum **`BehaviorMode`** (ids **0…6**), **`BEHAVIOR_MODES_IN_ORDER`**, **`DEFAULT_NEKO_BEHAVIOR_CYCLE`**, **`BehaviorCycle`**, **`isBehaviorMode`** — [`src/types/index.ts`](./src/types/index.ts); per-tick behaviors and movement state machine — [`src/runtime/nekoEngineMovement.ts`](./src/runtime/nekoEngineMovement.ts). **Readable strings (HUD / logs / hovers):** **`formatBehaviorMode`**, **`behaviorModeEnumName`**, **`BEHAVIOR_MODE_LABELS`**. **Stable cycle typing** (avoid inferred `0 \| 2 \| 1` unions): **`behaviorCycleOf(BehaviorMode.ChaseMouse, …)`**. **`NekoPet`** is cast to **`DefineComponent<NekoPetPublicProps>`** so Volar shows **`BehaviorMode`** on props, not plain `number`. Custom click order: **`behaviorCycle`**; invalid ids stripped in [`normalizeBehaviorCycle`](./src/runtime/nekojsRuntime.ts).
 - **`allowBehaviorChange`:** On `NekoPet`, default **`undefined`** so the field is omitted and the engine default **`true`** applies (see props table below).
+- **Click → next behavior:** When **`allowBehaviorChange`** is true, each pet **`mousedown`** advances **`behaviorCycle`**. Listen with **`onBehaviorModeChange`** in **`createNeko`** / **`useNeko`** options, or **`@behavior-mode-change`** on **`NekoPet`**. Set **`showBehaviorOnClick`** (or **`NekoOptions.showBehaviorOnClick`**) to show a short built-in **`BEHAVIOR_MODE_LABELS`** hint above the sprite.
 - **`restUntilFirstPetInteraction`:** First pointer-down wakes **`follow`** without consuming the first cycle step; then normal cycle. **`petInteractionAwake`** tracks this.
 - **Reduced motion:** Default **skip** load + create; **`skippedForReducedMotion`**. Opt out: **`respectReducedMotion: false`** (use with care). Helper: **`prefersReducedMotion()`** ([`src/utils/prefersReducedMotion.ts`](./src/utils/prefersReducedMotion.ts)).
 - **SSR:** Never run **`loadNekoRuntime`**, **`useNeko`**, or mount **`NekoPet`** on the server. **Nuxt 4:** [`.client.vue` + `#components` / auto-import](https://nuxt.com/docs/4.x/guide/directory-structure/components#client-components) and/or [`<ClientOnly>`](https://nuxt.com/docs/4.x/api/components/client-only).
@@ -59,37 +61,46 @@ Routing: [`playground/src/router.ts`](./playground/src/router.ts). Shell UI: [`p
 
 `defineComponent` in [`src/vue/NekoPet.ts`](./src/vue/NekoPet.ts). Exposes **`instance`** (**`shallowRef`**, unwrapped on parent component ref like **`useNeko`’s `instance`**).
 
-| Script | Template | Default | Notes |
-| ------ | -------- | ------- | ----- |
-| `speed` | `speed` | omit → **24** | Logic tick step; ~5 ticks/s in engine. |
-| `fps` | `fps` | omit → **120** | Animation interval. |
-| `behaviorMode` | `behavior-mode` | omit | Initial only; clicks change live mode. |
-| `idleThreshold` | `idle-threshold` | omit → **6** | Idle distance (px). |
-| `cursorStandoffPx` | `cursor-standoff-px` | omit / 0 | Chase: min distance from pointer. |
-| `allowBehaviorChange` | `allow-behavior-change` | **`undefined`** | `undefined` → engine default **true**; `false` disables click cycle. |
-| `behaviorCycle` | `behavior-cycle` | omit | → **`DEFAULT_NEKO_BEHAVIOR_CYCLE`**. |
-| `startX` / `startY` | `start-x` / `start-y` | omit | Home coords; **0** valid. |
-| `autoStart` | `auto-start` | **true** | Loop after create unless **`rest`** or **false**. |
-| `respectReducedMotion` | `respect-reduced-motion` | **true** | Skip when user prefers reduced motion. |
-| `startCorner` | `start-corner` | omit | `top-left` … `bottom-right` for missing axes. |
-| `anchorSelector` | `anchor-selector` | omit | `querySelector`; prefer **`anchorRef`** in **`useNeko`**. |
-| `mode` | `mode` | **follow** | `follow` \| `rest`. |
-| `restUntilFirstPetInteraction` | `rest-until-first-pet-interaction` | **`undefined`** | First click wakes follow. |
-| `debug` | `debug` | **false** | **`[neko-vue]`** placement / recreate logs. |
-
-**Option groups:** Engine — `speed`, `fps`, `behaviorMode`, `idleThreshold`, `cursorStandoffPx`, `behaviorCycle`, `allowBehaviorChange`, `startX`/`startY`. Placement — `startCorner`, `anchorRef` (composable) / `anchorSelector` (component). Loop — `mode`, `autoStart`, `respectReducedMotion`, `restUntilFirstPetInteraction`. Most engine/placement changes **recreate**; **`behaviorMode`** in options does not drive recreate except first create / gate exit.
+| Script                         | Template                           | Default         | Notes                                                                                                     |
+| ------------------------------ | ---------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
+| `speed`                        | `speed`                            | omit → **24**   | Logic tick step; ~5 ticks/s in engine.                                                                    |
+| `fps`                          | `fps`                              | omit → **120**  | Nominal display rate: the engine steps `update()` from **`requestAnimationFrame`** using `1000 / fps` ms. |
+| `behaviorMode`                 | `behavior-mode`                    | omit            | Initial only; clicks change live mode.                                                                    |
+| `idleThreshold`                | `idle-threshold`                   | omit → **6**    | Idle distance (px).                                                                                       |
+| `cursorStandoffPx`             | `cursor-standoff-px`               | omit / 0        | Chase: min distance from pointer.                                                                         |
+| `allowBehaviorChange`          | `allow-behavior-change`            | **`undefined`** | `undefined` → engine default **true**; `false` disables click cycle.                                      |
+| `behaviorCycle`                | `behavior-cycle`                   | omit            | → **`DEFAULT_NEKO_BEHAVIOR_CYCLE`**.                                                                      |
+| `startX` / `startY`            | `start-x` / `start-y`              | omit            | Home coords; **0** valid.                                                                                 |
+| `autoStart`                    | `auto-start`                       | **true**        | Loop after create unless **`rest`** or **false**.                                                         |
+| `respectReducedMotion`         | `respect-reduced-motion`           | **true**        | Skip when user prefers reduced motion.                                                                    |
+| `startCorner`                  | `start-corner`                     | omit            | `top-left` … `bottom-right` for missing axes.                                                             |
+| `anchorSelector`               | `anchor-selector`                  | omit            | `querySelector`; prefer **`anchorRef`** in **`useNeko`**.                                                 |
+| `mode`                         | `mode`                             | **follow**      | `follow` \| `rest`.                                                                                       |
+| `restUntilFirstPetInteraction` | `rest-until-first-pet-interaction` | **`undefined`** | First click wakes follow.                                                                                 |
+| `debug`                        | `debug`                            | **false**       | **`[neko-vue]`** placement / recreate logs.                                                               |
+| `showBehaviorOnClick`          | `show-behavior-on-click`           | **false**       | Built-in label above the sprite after each click cycle (needs **`allowBehaviorChange`**).                 |
+
+**Emits (`NekoPet`):** **`behaviorModeChange`** — payload is the new **`BehaviorMode`** after each pet click advances the cycle (same timing as **`onBehaviorModeChange`** on **`createNeko`** / **`useNeko`**).
+
+**Option groups:** Engine — `speed`, `fps`, `behaviorMode`, `idleThreshold`, `cursorStandoffPx`, `behaviorCycle`, `allowBehaviorChange`, `startX`/`startY`, **`onBehaviorModeChange`**, **`showBehaviorOnClick`**. Placement — `startCorner`, `anchorRef` (composable) / `anchorSelector` (component). Loop — `mode`, `autoStart`, `respectReducedMotion`, `restUntilFirstPetInteraction`. Most engine/placement changes **recreate**; **`behaviorMode`** in options does not drive recreate except first create / gate exit. **`onBehaviorModeChange`** identity changes also **recreate** (use a stable handler if undesired).
 
 ### `useNeko()` return value
 
-| Name | Type / role |
-| ---- | ----------- |
-| `instance` | `ShallowRef<NekoInstance \| null>` |
-| `error` | `Ref<Error \| null>` |
-| `isReady` | `Ref<boolean>` |
-| `skippedForReducedMotion` | `Ref<boolean>` |
-| `mode` | Readonly ref `follow` \| `rest` |
-| `petInteractionAwake` | Readonly ref (with **`restUntilFirstPetInteraction`**) |
-| `setMode`, `restAtOrigin`, `resumeFollow`, `destroy` | Imperative |
+| Name                                                 | Type / role                                            |
+| ---------------------------------------------------- | ------------------------------------------------------ |
+| `instance`                                           | `ShallowRef<NekoInstance \| null>`                     |
+| `error`                                              | `Ref<Error \| null>`                                   |
+| `isReady`                                            | `Ref<boolean>`                                         |
+| `skippedForReducedMotion`                            | `Ref<boolean>`                                         |
+| `mode`                                               | Readonly ref `follow` \| `rest`                        |
+| `petInteractionAwake`                                | Readonly ref (with **`restUntilFirstPetInteraction`**) |
+| `setMode`, `restAtOrigin`, `resumeFollow`, `destroy` | Imperative                                             |
+
+Options are **`UseNekoOptions`** = **`NekoOptions`** + placement / loop flags (`startCorner`, `anchorRef`, `mode`, …). Programmatic **`createNeko(opts)`** uses the same engine fields: **`onBehaviorModeChange`** (new mode after each click cycle), **`showBehaviorOnClick`** (built-in hint). Changing the **function identity** of **`onBehaviorModeChange`** or toggling **`showBehaviorOnClick`** **recreates** the pet; use a **stable** handler (e.g. a `function` declared once in `setup`) if you need to avoid that.
+
+### `NekoOptions` (engine / `createNeko`)
+
+Full interface: [`src/types/index.ts`](./src/types/index.ts). Besides motion and placement, notable fields include **`allowBehaviorChange`**, **`behaviorCycle`**, **`onBehaviorModeChange`**, and **`showBehaviorOnClick`**. The bundled runtime implements these in [`nekojsRuntime.ts`](./src/runtime/nekojsRuntime.ts) (`cycleBehavior`, hint element class **`neko-behavior-hint`**).
 
 ### `loadNekoRuntime()`
 
@@ -99,13 +110,13 @@ Routing: [`playground/src/router.ts`](./playground/src/router.ts). Shell UI: [`p
 
 [`package.json` `exports`](./package.json) + pack entries [`src/entries/*.ts`](./src/entries/) ([`vite.config.ts`](./vite.config.ts) **`pack.entry`**, **`pack.exports: false`**).
 
-| Import | Exposes |
-| ------ | ------- |
-| `neko-vue` | Full API ([`src/index.ts`](./src/index.ts)) |
-| `neko-vue/types` | Same as root type exports: behavior helpers **`formatBehaviorMode`**, **`behaviorModeEnumName`**, **`BEHAVIOR_MODE_LABELS`**, **`behaviorCycleOf`**, plus `BehaviorMode`, `BehaviorCycle`, etc. — no Vue |
-| `neko-vue/placement` | `cornerToStartXY`, `resolveStartPosition`, corners / input types |
-| `neko-vue/runtime` | `loadNekoRuntime` only |
-| `neko-vue/vue` | `useNeko`, `NekoPet`, **`NekoPetPublicProps`** (typed props for Volar), option types |
+| Import               | Exposes                                                                                                                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `neko-vue`           | Full API ([`src/index.ts`](./src/index.ts))                                                                                                                                                              |
+| `neko-vue/types`     | Same as root type exports: behavior helpers **`formatBehaviorMode`**, **`behaviorModeEnumName`**, **`BEHAVIOR_MODE_LABELS`**, **`behaviorCycleOf`**, plus `BehaviorMode`, `BehaviorCycle`, etc. — no Vue |
+| `neko-vue/placement` | `cornerToStartXY`, `resolveStartPosition`, corners / input types                                                                                                                                         |
+| `neko-vue/runtime`   | `loadNekoRuntime` only                                                                                                                                                                                   |
+| `neko-vue/vue`       | `useNeko`, `NekoPet`, **`NekoPetPublicProps`** (typed props for Volar), option types                                                                                                                     |
 
 ---
 
@@ -113,8 +124,10 @@ Routing: [`playground/src/router.ts`](./playground/src/router.ts). Shell UI: [`p
 
 - **Nothing draws:** Confirm the runtime **chunk** loads (Network). Check console.
 - **Skipped pet:** **`prefers-reduced-motion: reduce`** — intentional unless you set **`respectReducedMotion: false`** (with consent).
-- **Wrong corner on first paint:** Viewport **`clientWidth` / `innerHeight`** can be **0** briefly; **`debug: true`** logs resolved coords.
-- **Listeners / timers:** Unmount should call **`stop`** + **`destroy`**; engine uses **`AbortController`** ([`src/runtime/nekojsRuntime.ts`](./src/runtime/nekojsRuntime.ts)).
+- **Wrong corner on first paint:** Viewport **`clientWidth` / `innerHeight`** (or **`visualViewport`**) can be **0** briefly; **`debug: true`** logs resolved coords.
+- **Pet jumps when the window resizes:** Expected. Any layout change handled by the engine moves **`home`** and the sprite to **initial placement** clamped inside the new bounds (every **`behaviorMode`**, **`follow`** or **`rest`**). See [`nekoViewport.ts`](./src/runtime/nekoViewport.ts) + [`nekojsRuntime.ts`](./src/runtime/nekojsRuntime.ts); coverage in [`tests/neko.test.ts`](./tests/neko.test.ts) (`Neko resize`).
+- **Pet recreates on every parent render:** Often an **inline** **`onBehaviorModeChange`** (or other options) getting a **new function identity** each render — use a **stable** reference (see **`useNeko`** note above).
+- **Listeners / timers:** Unmount should call **`stop`** + **`destroy`**; engine uses **`AbortController`**, **`requestAnimationFrame`** for the draw loop, coalesced rAF for layout clamping, and clears behavior-hint timers ([`src/runtime/nekojsRuntime.ts`](./src/runtime/nekojsRuntime.ts)).
 
 ---
 
@@ -122,11 +135,13 @@ Routing: [`playground/src/router.ts`](./playground/src/router.ts). Shell UI: [`p
 
 Classic “one-file” neko demos often use a **GIF** or scalable strip. This engine uses **fixed 32×32** cells—use **`NEKOJS_SPRITE_SIZE`** for layout math. **HMR** in dev can briefly duplicate pets; **full refresh** fixes it. The runtime loads via a **single shared** dynamic import (separate bundler chunk); no alternate script URL at runtime.
 
+Logic ticks and movement live in [`nekoEngineMovement.ts`](./src/runtime/nekoEngineMovement.ts); viewport sizing in [`nekoViewport.ts`](./src/runtime/nekoViewport.ts); **`createNeko`** / DOM / lifecycle / click-cycle UI in [`nekojsRuntime.ts`](./src/runtime/nekojsRuntime.ts). The display loop is **rAF**-driven at the configured **`fps`**; in-engine logic still advances at the original ~**5** “original ticks” per second inside `update()`. Optional **`showBehaviorOnClick`** injects a **`.neko-behavior-hint`** child on the sprite root (overridable with your own CSS if needed).
+
 ---
 
 ## Development
 
-- **Layout:** `src/types`, `src/runtime`, `src/vue`, `src/placement`, `src/utils`, `src/entries` (subpath barrels), root [`src/index.ts`](./src/index.ts).
+- **Layout:** `src/types`, `src/runtime`, `src/vue`, `src/placement`, `src/utils`, `src/entries` (subpath barrels), root [`src/index.ts`](./src/index.ts). **Runtime:** [`nekojsRuntime.ts`](./src/runtime/nekojsRuntime.ts), [`nekoEngineMovement.ts`](./src/runtime/nekoEngineMovement.ts), [`nekoViewport.ts`](./src/runtime/nekoViewport.ts), [`loadNekoRuntime.ts`](./src/runtime/loadNekoRuntime.ts), [`nekoSpritesData.ts`](./src/runtime/nekoSpritesData.ts). Maintainer notes: [`plan.md`](./plan.md).
 - **Playground:** run / HMR / port **5175** — [`playground/README.md`](./playground/README.md).
 - **Scripts:** [`package.json`](./package.json) — `vp test`; `vp run check` & `vp run check:playground` (or `bun run check:all`); `vp pack`; `bun run playground:dev`. Do **not** run bare **`vp check`** on the whole tree (playground would resolve wrong `node_modules`).
 - **CI:** [`.github/workflows/ci.yml`](./.github/workflows/ci.yml).

package/dist/{NekoPet-BWrleApv.d.mts → NekoPet-C1UcoSGo.d.mts}

@@ -1,5 +1,5 @@
 import { n as NekoStartCorner } from "./nekoPlacement-fXmlU6ys.mjs";
-import { f as NekoInstance, i as BehaviorMode, p as NekoOptions, r as BehaviorCycle } from "./index-BGxU7veJ.mjs";
+import { f as NekoInstance, i as BehaviorMode, p as NekoOptions, r as BehaviorCycle } from "./index-CJBe9Tds.mjs";
 import * as _$vue from "vue";
 import { DefineComponent, MaybeRefOrGetter } from "vue";
 
@@ -15,6 +15,10 @@ type NekoFollowMode = "follow" | "rest";
  * If you wrap options in **`computed(() => ({ … }))`** and include `behaviorMode`, changing it still
  * invalidates that computed and may re-run internal watchers — use **`reactive`** for the options
  * object if you need to mutate `behaviorMode` without that effect.
+ *
+ * **`onBehaviorModeChange`** and **`showBehaviorOnClick`** are part of the recreate fingerprint; use a
+ * **stable** `onBehaviorModeChange` reference (e.g. a top-level function) if you do not want the pet
+ * recreated on every parent render.
  */
 type UseNekoOptions = NekoOptions & {
   /**
@@ -86,7 +90,7 @@ declare function useNeko(options?: MaybeRefOrGetter<UseNekoOptions | undefined>)
 interface NekoPetPublicProps {
   /** Pixels per engine logic tick (omit → default **24**). */
   speed?: number;
-  /** Sprite animation frame rate (omit → default **120**). */
+  /** Nominal display rate — engine steps from `requestAnimationFrame` at `1000 / fps` ms (omit → **120**). */
   fps?: number;
   /**
    * Initial {@link BehaviorMode} at create time. Clicks on the pet change the live mode when
@@ -146,6 +150,11 @@ interface NekoPetPublicProps {
   restUntilFirstPetInteraction?: boolean;
   /** Log placement / recreate steps with prefix `[neko-vue]`. */
   debug?: boolean;
+  /**
+   * When true, a short built-in label appears above the sprite after each click-to-cycle step
+   * (requires {@link allowBehaviorChange}).
+   */
+  showBehaviorOnClick?: boolean;
 }
 /**
  * Mounts the desktop pet on the client. Renders a minimal hidden root node for Vue; the engine draws

package/dist/{NekoPet-CsvPuZow.mjs → NekoPet-CLH3uMg0.mjs}

@@ -1,6 +1,6 @@
-import { r as BehaviorMode, u as isBehaviorMode } from "./types-De8imAgT.mjs";
-import { n as resolveStartPosition, r as nekoVueDebug } from "./nekoPlacement-CW-BnKgW.mjs";
-import { t as loadNekoRuntime } from "./loadNekoRuntime-BduhAtZ8.mjs";
+import { r as BehaviorMode, u as isBehaviorMode } from "./types-DGv86pPP.mjs";
+import { n as resolveStartPosition, r as nekoVueDebug } from "./nekoPlacement-DVX15n-h.mjs";
+import { t as loadNekoRuntime } from "./loadNekoRuntime-CarfwqJ5.mjs";
 import { computed, defineComponent, h, onBeforeUnmount, onMounted, readonly, ref, shallowRef, toValue, watch, watchEffect } from "vue";
 //#region src/utils/prefersReducedMotion.ts
 /**
@@ -134,6 +134,7 @@ function useNeko(options = {}) {
 			if ((toValue(options) ?? {}).restUntilFirstPetInteraction !== true || petInteractionAwake.value) return;
 			if (typeof document === "undefined") return;
 			const onPointerDown = (e) => {
+				if (petInteractionAwake.value) return;
 				const pet = document.querySelector(".neko");
 				const t = e.target;
 				if (!pet || !(t instanceof Node) || !(pet === t || pet.contains(t))) return;
@@ -188,7 +189,9 @@ function useNeko(options = {}) {
 				autoStart: raw.autoStart,
 				respectReducedMotion: raw.respectReducedMotion,
 				anchorSelector: raw.anchorSelector,
-				debug: raw.debug
+				debug: raw.debug,
+				showBehaviorOnClick: raw.showBehaviorOnClick === true,
+				onBehaviorModeChange: raw.onBehaviorModeChange
 			};
 		}, async () => {
 			const gen = ++mountGen;
@@ -337,6 +340,7 @@ function useNeko(options = {}) {
 */
 var NekoPet_default = defineComponent({
 	name: "NekoPet",
+	emits: { behaviorModeChange: (mode) => isBehaviorMode(mode) },
 	props: {
 		speed: Number,
 		fps: Number,
@@ -371,9 +375,16 @@ var NekoPet_default = defineComponent({
 		debug: {
 			type: Boolean,
 			default: false
+		},
+		showBehaviorOnClick: {
+			type: Boolean,
+			default: false
 		}
 	},
-	setup(props, { expose }) {
+	setup(props, { expose, emit }) {
+		const notifyBehaviorModeChange = (mode) => {
+			emit("behaviorModeChange", mode);
+		};
 		const { instance } = useNeko(computed(() => ({
 			speed: props.speed,
 			fps: props.fps,
@@ -390,7 +401,9 @@ var NekoPet_default = defineComponent({
 			anchorSelector: props.anchorSelector || void 0,
 			mode: props.mode,
 			restUntilFirstPetInteraction: props.restUntilFirstPetInteraction,
-			debug: props.debug
+			debug: props.debug,
+			showBehaviorOnClick: props.showBehaviorOnClick,
+			onBehaviorModeChange: notifyBehaviorModeChange
 		})));
 		expose({ instance });
 		return () => h("span", {

package/dist/{index-BGxU7veJ.d.mts → index-CJBe9Tds.d.mts}

@@ -1,8 +1,8 @@
 //#region src/types/index.d.ts
-/** Sprite edge length in CSS pixels for viewport bounds (`clientWidth/innerHeight - this`). */
+/** Sprite edge length in CSS pixels for viewport bounds (see runtime `readViewportBounds`). */
 declare const NEKOJS_SPRITE_SIZE: 32;
 /**
- * Pet behavior / AI mode. Numeric values **must** match the bundled engine (`src/runtime/nekojsRuntime.ts`).
+ * Pet behavior / AI mode. Numeric values **must** match the bundled engine (`src/runtime/nekoEngineMovement.ts`).
  * Click cycles through {@link NekoOptions.behaviorCycle} when `allowBehaviorChange` is true.
  */
 declare enum BehaviorMode {
@@ -70,8 +70,9 @@ declare function behaviorCycleOf(...modes: BehaviorMode[]): BehaviorCycle;
  *
  * Numeric defaults use **nullish coalescing** (`??`): omit or pass `undefined` for engine defaults;
  * **`0` is a real value** for `speed`, `fps`, `idleThreshold`, `startX`, and `startY` on this interface.
- * Horizontal bounds use `document.documentElement.clientWidth - {@link NEKOJS_SPRITE_SIZE}`; vertical uses
- * `window.innerHeight - {@link NEKOJS_SPRITE_SIZE}`.
+ * Bounds: `visualViewport` width/height (when available and positive) or else
+ * `document.documentElement.clientWidth` / `window.innerHeight`, each minus {@link NEKOJS_SPRITE_SIZE}
+ * (see runtime `readViewportBounds`).
  */
 interface NekoOptions {
   /**
@@ -79,7 +80,8 @@ interface NekoOptions {
    */
   speed?: number;
   /**
-   * Render frame rate (default **120** when omitted).
+   * Nominal display rate (default **120** when omitted). The bundled engine steps `update()` from
+   * `requestAnimationFrame` using `1000 / fps` ms between steps.
    */
   fps?: number;
   /**
@@ -115,15 +117,27 @@ interface NekoOptions {
    * Initial Y position. `0` is valid; omit for default `0`.
    */
   startY?: number;
+  /**
+   * Called after each pet click advances the live {@link behaviorMode} (when
+   * {@link allowBehaviorChange} is true). Receives the **new** mode. Captured when the instance is
+   * created; changing this reference in `useNeko` options triggers recreate (use a stable function
+   * if you want to avoid that).
+   */
+  onBehaviorModeChange?: (mode: BehaviorMode) => void;
+  /**
+   * When true, a short built-in label appears above the sprite with the new behavior’s
+   * {@link BEHAVIOR_MODE_LABELS} text after each successful click cycle step.
+   */
+  showBehaviorOnClick?: boolean;
 }
 /**
  * Minimal handle returned by {@link createNeko} / {@link loadNekoRuntime}. The bundled engine may
  * expose additional helpers (e.g. `isIdle`).
  */
 interface NekoInstance {
-  /** Starts or resumes the animation interval. */
+  /** Starts or resumes the `requestAnimationFrame` animation loop. */
   start(): void;
-  /** Stops the interval without removing the pet from the DOM. */
+  /** Stops the animation loop without removing the pet from the DOM. */
   stop(): void;
   /** Stops the loop, removes listeners, and deletes the pet element. */
   destroy(): void;
@@ -142,6 +156,16 @@ interface NekoInstance {
    */
   homeX?: number;
   homeY?: number;
+  /**
+   * Bundled engine only — whether the sprite is in a stationary / idle animation state.
+   * Test mocks may omit.
+   */
+  isIdle?(): boolean;
+  /**
+   * Bundled engine only — assign PNG/Data URL frames for the sprite. Used internally by `createNeko`.
+   * Test mocks may omit.
+   */
+  setSprites?(sprites: readonly string[]): void;
 }
 /** All mutable fields for the viewport-fixed pet engine (closure-scoped; used by `nekojsRuntime`). */
 type NekoEngineState = {
@@ -170,6 +194,7 @@ type NekoEngineState = {
   mouseY: number | null;
   hasMouseMoved: boolean;
   element: HTMLDivElement;
+  spriteImg: HTMLImageElement;
   spriteImages: string[];
   allowBehaviorChange: boolean;
   animationTable: [number, number][];
@@ -177,17 +202,24 @@ type NekoEngineState = {
   ballX: number;
   ballY: number;
   ballVX: number;
-  ballVY: number;
+  ballVY: number; /** Set when ball-chase mode has spawned the invisible ball; cleared when leaving that mode. */
+  ballActive: boolean;
   running: boolean;
-  intervalId: ReturnType<typeof setInterval> | null;
+  animationFrameId: number | null;
   tickAccumulator: number;
   actionCount: number;
   lastMoveDX: number;
   lastMoveDY: number;
   cursorStandoffPx: number;
-  behaviorCycle: readonly BehaviorMode[];
+  behaviorCycle: readonly BehaviorMode[]; /** Initial spawn/home from options; re-clamped on resize so the viewport can grow again. */
+  placementHomeX: number;
+  placementHomeY: number;
   homeX: number;
-  homeY: number;
+  homeY: number; /** From {@link NekoOptions.onBehaviorModeChange}; invoked after each click cycle step. */
+  onBehaviorModeChange?: (mode: BehaviorMode) => void; /** From {@link NekoOptions.showBehaviorOnClick}. */
+  showBehaviorOnClick: boolean; /** Built-in behavior label element; cleaned up in `destroy`. */
+  behaviorHintEl: HTMLDivElement | null; /** Browser timer id from `window.setTimeout` (numeric in DOM typings). */
+  behaviorHintTimeoutId: number | null;
 };
 /** Full engine handle: {@link NekoInstance} plus internal helpers (`setSprites`, `isIdle`). */
 type NekoEngineApi = NekoInstance & {

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { i as resolveStartPosition, n as NekoStartCorner, r as cornerToStartXY } from "./nekoPlacement-fXmlU6ys.mjs";
-import { _ as isBehaviorMode, a as BehaviorModes, c as LoadNekoRuntimeOptions, d as NekoEngineState, f as NekoInstance, g as formatBehaviorMode, h as behaviorModeEnumName, i as BehaviorMode, l as NEKOJS_SPRITE_SIZE, m as behaviorCycleOf, n as BEHAVIOR_MODE_LABELS, o as CreateNekoFn, p as NekoOptions, r as BehaviorCycle, s as DEFAULT_NEKO_BEHAVIOR_CYCLE, t as BEHAVIOR_MODES_IN_ORDER, u as NekoEngineApi } from "./index-BGxU7veJ.mjs";
-import { t as loadNekoRuntime } from "./loadNekoRuntime-BqOla6to.mjs";
-import { a as useNeko, i as UseNekoOptions, n as _default, r as NekoFollowMode, t as NekoPetPublicProps } from "./NekoPet-BWrleApv.mjs";
+import { _ as isBehaviorMode, a as BehaviorModes, c as LoadNekoRuntimeOptions, d as NekoEngineState, f as NekoInstance, g as formatBehaviorMode, h as behaviorModeEnumName, i as BehaviorMode, l as NEKOJS_SPRITE_SIZE, m as behaviorCycleOf, n as BEHAVIOR_MODE_LABELS, o as CreateNekoFn, p as NekoOptions, r as BehaviorCycle, s as DEFAULT_NEKO_BEHAVIOR_CYCLE, t as BEHAVIOR_MODES_IN_ORDER, u as NekoEngineApi } from "./index-CJBe9Tds.mjs";
+import { t as loadNekoRuntime } from "./loadNekoRuntime-DdKHhZUx.mjs";
+import { a as useNeko, i as UseNekoOptions, n as _default, r as NekoFollowMode, t as NekoPetPublicProps } from "./NekoPet-C1UcoSGo.mjs";
 
 //#region src/utils/debugLog.d.ts
 /** Opt-in `console` helper; prefix keeps DevTools filter easy. */

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { a as DEFAULT_NEKO_BEHAVIOR_CYCLE, c as behaviorModeEnumName, i as BehaviorModes, l as formatBehaviorMode, n as BEHAVIOR_MODE_LABELS, o as NEKOJS_SPRITE_SIZE, r as BehaviorMode, s as behaviorCycleOf, t as BEHAVIOR_MODES_IN_ORDER, u as isBehaviorMode } from "./types-De8imAgT.mjs";
-import { n as resolveStartPosition, r as nekoVueDebug, t as cornerToStartXY } from "./nekoPlacement-CW-BnKgW.mjs";
-import { t as loadNekoRuntime } from "./loadNekoRuntime-BduhAtZ8.mjs";
-import { n as useNeko, r as prefersReducedMotion, t as NekoPet_default } from "./NekoPet-CsvPuZow.mjs";
+import { a as DEFAULT_NEKO_BEHAVIOR_CYCLE, c as behaviorModeEnumName, i as BehaviorModes, l as formatBehaviorMode, n as BEHAVIOR_MODE_LABELS, o as NEKOJS_SPRITE_SIZE, r as BehaviorMode, s as behaviorCycleOf, t as BEHAVIOR_MODES_IN_ORDER, u as isBehaviorMode } from "./types-DGv86pPP.mjs";
+import { n as resolveStartPosition, r as nekoVueDebug, t as cornerToStartXY } from "./nekoPlacement-DVX15n-h.mjs";
+import { t as loadNekoRuntime } from "./loadNekoRuntime-CarfwqJ5.mjs";
+import { n as useNeko, r as prefersReducedMotion, t as NekoPet_default } from "./NekoPet-CLH3uMg0.mjs";
 export { BEHAVIOR_MODES_IN_ORDER, BEHAVIOR_MODE_LABELS, BehaviorMode, BehaviorModes, DEFAULT_NEKO_BEHAVIOR_CYCLE, NEKOJS_SPRITE_SIZE, NekoPet_default as NekoPet, behaviorCycleOf, behaviorModeEnumName, cornerToStartXY, formatBehaviorMode, isBehaviorMode, loadNekoRuntime, nekoVueDebug, prefersReducedMotion, resolveStartPosition, useNeko };

package/dist/{loadNekoRuntime-BduhAtZ8.mjs → loadNekoRuntime-CarfwqJ5.mjs}

@@ -12,7 +12,7 @@ let bundledLoadPromise = null;
 * Dynamically imports the bundled typed runtime (`./nekojsRuntime.ts`). Defines `window.createNeko`.
 */
 async function importBundledNeko() {
-	await import("./nekojsRuntime-CiPaD_IV.mjs");
+	await import("./nekojsRuntime-2Ax6jUB6.mjs");
 	const fn = getCreateNekoFromGlobal();
 	if (!fn) throw new Error("neko-vue: bundled neko.js did not define `createNeko`.");
 	return fn;

package/dist/{loadNekoRuntime-BqOla6to.d.mts → loadNekoRuntime-DdKHhZUx.d.mts}

@@ -1,4 +1,4 @@
-import { c as LoadNekoRuntimeOptions, o as CreateNekoFn } from "./index-BGxU7veJ.mjs";
+import { c as LoadNekoRuntimeOptions, o as CreateNekoFn } from "./index-CJBe9Tds.mjs";
 
 //#region src/runtime/loadNekoRuntime.d.ts
 /**

package/dist/{nekoPlacement-CW-BnKgW.mjs → nekoPlacement-DVX15n-h.mjs}

@@ -1,4 +1,4 @@
-import "./types-De8imAgT.mjs";
+import "./types-DGv86pPP.mjs";
 //#region src/utils/debugLog.ts
 /** Opt-in `console` helper; prefix keeps DevTools filter easy. */
 function nekoVueDebug(enabled, label, ...args) {