neko-vue 0.1.0

package/dist/NekoPet-B9k9Bf1o.d.mts

@@ -0,0 +1,262 @@
+import { n as NekoStartCorner } from "./nekoPlacement-fXmlU6ys.mjs";
+import { c as NekoOptions, s as NekoInstance, t as BehaviorMode } from "./index-BjAaI8iZ.mjs";
+import * as _$vue from "vue";
+import { MaybeRefOrGetter, PropType } from "vue";
+
+//#region src/vue/useNeko.d.ts
+/** Whether the pet chases the pointer or stays at the resolved start position. */
+type NekoFollowMode = "follow" | "rest";
+/**
+ * Options for {@link useNeko}. Includes all {@link NekoOptions} fields plus placement and
+ * wrapper-only flags. Omitted fields are left unset so engine defaults apply where applicable.
+ *
+ * **`behaviorMode`** is read for the **first** create and when leaving the pet-interaction gate; it
+ * is **not** part of the recreate fingerprint. Live mode changes come from **clicking the pet**.
+ * 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.
+ */
+type UseNekoOptions = NekoOptions & {
+  /**
+   * When true (default), run the animation loop after `createNeko`.
+   * The engine’s `createNeko` always calls `start()` internally; when this is false or `mode` is `rest`,
+   * we call `stop()` immediately after creation.
+   */
+  autoStart?: boolean;
+  /**
+   * When true (default), do not load or create the pet if the user prefers reduced motion
+   * (see {@link prefersReducedMotion}). Set false to always run (e.g. user override).
+   */
+  respectReducedMotion?: boolean; /** Place the pet at a viewport corner unless `startX` / `startY` override that axis. */
+  startCorner?: NekoStartCorner;
+  /**
+   * Use this element’s top-left (viewport) for `startX`/`startY` when those are omitted.
+   * When set, **`createNeko` is deferred** until the element is non-null and
+   * `getBoundingClientRect()` has **positive width and height** (avoids a bogus spawn while the anchor is still mounting or collapsed).
+   */
+  anchorRef?: MaybeRefOrGetter<HTMLElement | null | undefined>;
+  /**
+   * `document.querySelector` (client only). Prefer `anchorRef` in `setup`.
+   * Uses the same **layout gate** as `anchorRef`: no create until a match exists with non-zero size.
+   */
+  anchorSelector?: string; /** `follow` = chase; `rest` = remain at resolved home position (animation loop stopped). */
+  mode?: MaybeRefOrGetter<NekoFollowMode>; /** When true, logs placement and lifecycle to the console with prefix `[neko-vue]`. */
+  debug?: boolean;
+  /**
+   * When true, the pet starts **still** (`rest`) with a one-time setup so the **first** pointer down
+   * on the sprite wakes **follow** (chase) **without** consuming the built-in click-to-cycle step.
+   * Further pointer downs use the full click cycle (through stay still and return home & stay).
+   *
+   * While waiting for that first interaction, `behaviorMode` is forced to {@link BehaviorMode.StayStill} so the
+   * engine idles even if a frame runs before the wrapper calls `stop()`; we intercept the first pointer instead.
+   * `allowBehaviorChange` is forced **true** during the wait so the sprite stays clickable.
+   */
+  restUntilFirstPetInteraction?: boolean;
+};
+/**
+ * Create a pet instance on mount and destroy it on unmount.
+ * Options may be reactive; when they change, the previous instance is destroyed and a new one is created.
+ *
+ * **Viewport-fixed pet:** the sprite lives on `document`, not under your component tree. This composable
+ * only manages **lifecycle** and **placement inputs** (`startX`/`startY`, corners, anchor); it does not
+ * reparent the engine’s DOM without upstream support.
+ *
+ * The engine’s `createNeko` always calls `start()`; this composable may call `stop()` right after to honor
+ * `autoStart`, `mode: 'rest'`, or both.
+ */
+declare function useNeko(options?: MaybeRefOrGetter<UseNekoOptions | undefined>): {
+  /** Live `NekoInstance` after load and `createNeko`, or null before ready / after destroy. */instance: _$vue.ShallowRef<NekoInstance | null, NekoInstance | null>; /** Set when runtime load or `createNeko` fails; cleared on successful recreate. */
+  error: _$vue.Ref<Error | null, Error | null>; /** True once `createNeko` has run successfully for the current mount cycle. */
+  isReady: _$vue.Ref<boolean, boolean>; /** True when the pet was skipped because `respectReducedMotion` matched user preference. */
+  skippedForReducedMotion: _$vue.Ref<boolean, boolean>; /** Current `follow` / `rest` mode (readonly); drive with {@link setMode} or a reactive `mode` in options. */
+  mode: Readonly<_$vue.Ref<NekoFollowMode, NekoFollowMode>>; /** True after the first pet pointer-down when `restUntilFirstPetInteraction` is enabled. */
+  petInteractionAwake: Readonly<_$vue.Ref<boolean, boolean>>; /** Imperatively set `follow` or `rest` (updates internal `mode` ref used by the pet). */
+  setMode: (m: NekoFollowMode) => void;
+  restAtOrigin: () => void;
+  resumeFollow: () => void; /** Stop, destroy the instance, and clear ready state (does not tear down composable watchers). */
+  destroy: () => void;
+};
+//#endregion
+//#region src/vue/NekoPet.d.ts
+/**
+ * Mounts the desktop pet on the client. Renders a minimal hidden root node for Vue; the engine draws
+ * **viewport-fixed** on `document` — not as a child of your layout. Placement is **lifecycle + options**
+ * (`startX` / `startY`, `startCorner`, `anchorRef` / `anchorSelector`); a true DOM parent for the sprite
+ * would require upstream engine changes.
+ */
+declare const _default: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
+  speed: NumberConstructor;
+  fps: NumberConstructor;
+  /**
+   * Initial {@link BehaviorMode} at create time. Clicks on the pet change the live mode when
+   * {@link allowBehaviorChange} is true; updating this prop does not recreate or override the
+   * current mode.
+   */
+  behaviorMode: PropType<BehaviorMode | undefined>;
+  /**
+   * Distance (px) at which the pet counts as idle for behavior logic (engine default: 6).
+   */
+  idleThreshold: NumberConstructor;
+  /**
+   * Chase mode: stay at least this many pixels from the pointer (omit or 0 for default snap-to-cursor).
+   */
+  cursorStandoffPx: NumberConstructor;
+  /**
+   * When clicking the pet may cycle {@link BehaviorMode}. Omit this prop to use the engine default
+   * (`true`). A plain optional boolean prop would be `false` when absent; here `default: undefined`
+   * so `createNeko` omits the field and engine defaults apply.
+   */
+  allowBehaviorChange: {
+    type: BooleanConstructor;
+    default: undefined;
+  };
+  /**
+   * Pet-click mode order when {@link allowBehaviorChange} is true. Omit for the bundled default
+   * seven-step cycle.
+   */
+  behaviorCycle: PropType<BehaviorMode[] | undefined>; /** Initial X in viewport pixels. `0` is valid; the engine treats omitted as `0`. */
+  startX: NumberConstructor; /** Initial Y in viewport pixels. `0` is valid; the engine treats omitted as `0`. */
+  startY: NumberConstructor;
+  /**
+   * When true (default), keep the animation loop running after `createNeko`. The engine always calls
+   * `start()` inside `createNeko`; when false or when {@link mode} is `rest`, the wrapper calls
+   * `stop()` right after creation.
+   */
+  autoStart: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * When true (default), skip loading and creating the pet if the user prefers reduced motion
+   * (see {@link prefersReducedMotion}). Set false to always run (e.g. after explicit user consent).
+   */
+  respectReducedMotion: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * Place the pet at a viewport corner for any axis where {@link startX} / {@link startY} are omitted.
+   */
+  startCorner: PropType<NekoStartCorner | undefined>;
+  /**
+   * `document.querySelector` for an anchor element (client only). When set, `startX`/`startY` for
+   * omitted axes use the element’s top-left in viewport space. `createNeko` waits until a match exists
+   * with positive width and height. Prefer {@link useNeko}'s `anchorRef` in script when you have a ref.
+   */
+  anchorSelector: StringConstructor;
+  /**
+   * `follow` — chase / run behaviors (loop running). `rest` — stay at the resolved home position
+   * (loop stopped after each create).
+   */
+  mode: {
+    type: PropType<NekoFollowMode>;
+    default: string;
+  };
+  /**
+   * When true, start in `rest`; the first pointer down on the sprite switches to `follow` without
+   * consuming the engine’s first click-to-cycle step. Later clicks use the full cycle (including stay still and return home).
+   * While waiting, {@link behaviorMode} is forced to {@link BehaviorMode.StayStill} and
+   * {@link allowBehaviorChange} to true so the sprite stays clickable.
+   */
+  restUntilFirstPetInteraction: {
+    type: BooleanConstructor;
+    default: undefined;
+  }; /** Log placement and recreate steps to the console with prefix `[neko-vue]`. */
+  debug: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+}>, () => _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<_$vue.ExtractPropTypes<{
+  speed: NumberConstructor;
+  fps: NumberConstructor;
+  /**
+   * Initial {@link BehaviorMode} at create time. Clicks on the pet change the live mode when
+   * {@link allowBehaviorChange} is true; updating this prop does not recreate or override the
+   * current mode.
+   */
+  behaviorMode: PropType<BehaviorMode | undefined>;
+  /**
+   * Distance (px) at which the pet counts as idle for behavior logic (engine default: 6).
+   */
+  idleThreshold: NumberConstructor;
+  /**
+   * Chase mode: stay at least this many pixels from the pointer (omit or 0 for default snap-to-cursor).
+   */
+  cursorStandoffPx: NumberConstructor;
+  /**
+   * When clicking the pet may cycle {@link BehaviorMode}. Omit this prop to use the engine default
+   * (`true`). A plain optional boolean prop would be `false` when absent; here `default: undefined`
+   * so `createNeko` omits the field and engine defaults apply.
+   */
+  allowBehaviorChange: {
+    type: BooleanConstructor;
+    default: undefined;
+  };
+  /**
+   * Pet-click mode order when {@link allowBehaviorChange} is true. Omit for the bundled default
+   * seven-step cycle.
+   */
+  behaviorCycle: PropType<BehaviorMode[] | undefined>; /** Initial X in viewport pixels. `0` is valid; the engine treats omitted as `0`. */
+  startX: NumberConstructor; /** Initial Y in viewport pixels. `0` is valid; the engine treats omitted as `0`. */
+  startY: NumberConstructor;
+  /**
+   * When true (default), keep the animation loop running after `createNeko`. The engine always calls
+   * `start()` inside `createNeko`; when false or when {@link mode} is `rest`, the wrapper calls
+   * `stop()` right after creation.
+   */
+  autoStart: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * When true (default), skip loading and creating the pet if the user prefers reduced motion
+   * (see {@link prefersReducedMotion}). Set false to always run (e.g. after explicit user consent).
+   */
+  respectReducedMotion: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  /**
+   * Place the pet at a viewport corner for any axis where {@link startX} / {@link startY} are omitted.
+   */
+  startCorner: PropType<NekoStartCorner | undefined>;
+  /**
+   * `document.querySelector` for an anchor element (client only). When set, `startX`/`startY` for
+   * omitted axes use the element’s top-left in viewport space. `createNeko` waits until a match exists
+   * with positive width and height. Prefer {@link useNeko}'s `anchorRef` in script when you have a ref.
+   */
+  anchorSelector: StringConstructor;
+  /**
+   * `follow` — chase / run behaviors (loop running). `rest` — stay at the resolved home position
+   * (loop stopped after each create).
+   */
+  mode: {
+    type: PropType<NekoFollowMode>;
+    default: string;
+  };
+  /**
+   * When true, start in `rest`; the first pointer down on the sprite switches to `follow` without
+   * consuming the engine’s first click-to-cycle step. Later clicks use the full cycle (including stay still and return home).
+   * While waiting, {@link behaviorMode} is forced to {@link BehaviorMode.StayStill} and
+   * {@link allowBehaviorChange} to true so the sprite stays clickable.
+   */
+  restUntilFirstPetInteraction: {
+    type: BooleanConstructor;
+    default: undefined;
+  }; /** Log placement and recreate steps to the console with prefix `[neko-vue]`. */
+  debug: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+}>> & Readonly<{}>, {
+  allowBehaviorChange: boolean;
+  autoStart: boolean;
+  respectReducedMotion: boolean;
+  mode: NekoFollowMode;
+  restUntilFirstPetInteraction: boolean;
+  debug: boolean;
+}, {}, {}, {}, string, _$vue.ComponentProvideOptions, true, {}, any>;
+//#endregion
+export { useNeko as i, NekoFollowMode as n, UseNekoOptions as r, _default as t };

package/dist/NekoPet-DMPjoHm0.mjs

@@ -0,0 +1,402 @@
+import { t as BehaviorMode } from "./types-Ctrldouo.mjs";
+import { n as resolveStartPosition, r as nekoVueDebug } from "./nekoPlacement-DUdnhZoX.mjs";
+import { t as loadNekoRuntime } from "./loadNekoRuntime-CskWI70T.mjs";
+import { computed, defineComponent, h, onBeforeUnmount, onMounted, readonly, ref, shallowRef, toValue, watch, watchEffect } from "vue";
+//#region src/utils/prefersReducedMotion.ts
+/**
+* True when the user has requested less motion (OS / browser setting).
+* Safe on SSR (returns false) and when `matchMedia` is missing.
+*/
+function prefersReducedMotion() {
+	if (typeof window === "undefined") return false;
+	try {
+		return window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/vue/useNeko.ts
+function pickNekoOptions(o) {
+	const { autoStart: _a, respectReducedMotion: _r, startCorner: _c, anchorRef: _ar, anchorSelector: _as, mode: _m, debug: _d, restUntilFirstPetInteraction: _wake, ...neko } = o;
+	return neko;
+}
+function resolveAnchorElement(o) {
+	if (o.anchorRef != null) {
+		const el = toValue(o.anchorRef);
+		if (el) return el;
+	}
+	if (o.anchorSelector && typeof document !== "undefined") return document.querySelector(o.anchorSelector);
+	return null;
+}
+/** User configured an anchor (ref or selector) — wait for a real, non-collapsed box before `createNeko`. */
+function wantsAnchorBinding(o) {
+	return o.anchorRef != null || Boolean(o.anchorSelector);
+}
+function isAnchorLaidOutForCreate(anchorEl) {
+	if (!anchorEl) return false;
+	const r = anchorEl.getBoundingClientRect();
+	const w = r.width > 0 ? r.width : anchorEl.offsetWidth;
+	const h = r.height > 0 ? r.height : anchorEl.offsetHeight;
+	return w > 0 && h > 0;
+}
+function buildPlacementInput(o) {
+	return {
+		startX: o.startX,
+		startY: o.startY,
+		startCorner: o.startCorner,
+		anchorElement: resolveAnchorElement(o)
+	};
+}
+/** The engine treats a missing key as its default; strip `undefined` so we never override with implicit Vue prop values. */
+function omitUndefinedNekoFields(opts) {
+	return Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== void 0));
+}
+function buildCreateOptions(o, petGateClosed) {
+	const debug = o.debug === true;
+	const base = pickNekoOptions(o);
+	const { startX, startY } = resolveStartPosition(buildPlacementInput(o), debug);
+	let merged = {
+		...base,
+		startX,
+		startY
+	};
+	if (petGateClosed && o.restUntilFirstPetInteraction) merged = {
+		...merged,
+		behaviorMode: BehaviorMode.StayStill,
+		allowBehaviorChange: true
+	};
+	return omitUndefinedNekoFields(merged);
+}
+function readInstanceBehaviorMode(inst) {
+	if (!inst) return;
+	const v = inst.behaviorMode;
+	return typeof v === "number" ? v : void 0;
+}
+/**
+* `behaviorMode` in options is only for **initial** create; reactive changes must not recreate.
+* On recreate (anchor/layout/mode…), keep the live engine mode unless we just left the
+* `restUntilFirstPetInteraction` gate (then apply the parent’s initial mode again).
+*/
+function applyBehaviorModeForRecreate(nekoOpts, raw, petGateClosed, priorBm, leavingPetGate) {
+	if (petGateClosed && raw.restUntilFirstPetInteraction) return;
+	if (leavingPetGate) {
+		if (raw.behaviorMode !== void 0) nekoOpts.behaviorMode = raw.behaviorMode;
+		else delete nekoOpts.behaviorMode;
+		return;
+	}
+	if (priorBm !== void 0) nekoOpts.behaviorMode = priorBm;
+}
+function anchorElementRectKey(el) {
+	const r = el.getBoundingClientRect();
+	return [
+		r.left,
+		r.top,
+		r.width,
+		r.height
+	].map((n) => Math.round(n * 100) / 100).join(",");
+}
+/**
+* Create a pet instance on mount and destroy it on unmount.
+* Options may be reactive; when they change, the previous instance is destroyed and a new one is created.
+*
+* **Viewport-fixed pet:** the sprite lives on `document`, not under your component tree. This composable
+* only manages **lifecycle** and **placement inputs** (`startX`/`startY`, corners, anchor); it does not
+* reparent the engine’s DOM without upstream support.
+*
+* The engine’s `createNeko` always calls `start()`; this composable may call `stop()` right after to honor
+* `autoStart`, `mode: 'rest'`, or both.
+*/
+function useNeko(options = {}) {
+	const instance = shallowRef(null);
+	const error = ref(null);
+	const isReady = ref(false);
+	const skippedForReducedMotion = ref(false);
+	const modeRef = ref("follow");
+	const anchorLayoutTick = ref(0);
+	/** After first pet pointer-down when `restUntilFirstPetInteraction` is enabled. */
+	const petInteractionAwake = ref(false);
+	/** True while the live instance was created under the pet-interaction gate (ball-chase wait). */
+	const petGateSpawnedInstance = ref(false);
+	let stopModeWatch;
+	let stopMainWatch;
+	let stopWakeOptionWatch;
+	let mountGen = 0;
+	onMounted(() => {
+		stopModeWatch = watch(() => toValue(options)?.mode, (m) => {
+			if (m !== void 0) modeRef.value = toValue(m);
+		}, { immediate: true });
+		stopWakeOptionWatch = watch(() => toValue(options)?.restUntilFirstPetInteraction === true, (enabled) => {
+			if (!enabled) petInteractionAwake.value = false;
+		});
+		watchEffect((onCleanup) => {
+			if ((toValue(options) ?? {}).restUntilFirstPetInteraction !== true || petInteractionAwake.value) return;
+			if (typeof document === "undefined") return;
+			const onPointerDown = (e) => {
+				const pet = document.querySelector(".neko");
+				const t = e.target;
+				if (!pet || !(t instanceof Node) || !(pet === t || pet.contains(t))) return;
+				e.preventDefault();
+				e.stopImmediatePropagation();
+				petInteractionAwake.value = true;
+			};
+			document.addEventListener("mousedown", onPointerDown, true);
+			onCleanup(() => {
+				document.removeEventListener("mousedown", onPointerDown, true);
+			});
+		});
+		watchEffect((onCleanup) => {
+			const raw = toValue(options) ?? {};
+			const el = raw.anchorRef != null ? toValue(raw.anchorRef) : null;
+			if (!el || typeof ResizeObserver === "undefined") return;
+			let lastRectKey = anchorElementRectKey(el);
+			const ro = new ResizeObserver(() => {
+				const next = anchorElementRectKey(el);
+				if (next === lastRectKey) return;
+				lastRectKey = next;
+				anchorLayoutTick.value++;
+			});
+			ro.observe(el);
+			onCleanup(() => {
+				ro.disconnect();
+			});
+		});
+		stopMainWatch = watch(() => {
+			const raw = toValue(options) ?? {};
+			const rect = resolveAnchorElement(raw)?.getBoundingClientRect();
+			return {
+				mode: modeRef.value,
+				anchorTick: anchorLayoutTick.value,
+				anchorRect: rect ? {
+					x: rect.x,
+					y: rect.y,
+					w: rect.width,
+					h: rect.height
+				} : null,
+				petInteractionAwake: petInteractionAwake.value,
+				restUntilFirstPetInteraction: raw.restUntilFirstPetInteraction === true,
+				speed: raw.speed,
+				fps: raw.fps,
+				idleThreshold: raw.idleThreshold,
+				cursorStandoffPx: raw.cursorStandoffPx,
+				behaviorCycle: JSON.stringify(raw.behaviorCycle ?? null),
+				allowBehaviorChange: raw.allowBehaviorChange,
+				startCorner: raw.startCorner,
+				startX: raw.startX,
+				startY: raw.startY,
+				autoStart: raw.autoStart,
+				respectReducedMotion: raw.respectReducedMotion,
+				anchorSelector: raw.anchorSelector,
+				debug: raw.debug
+			};
+		}, async () => {
+			const gen = ++mountGen;
+			const raw = toValue(options) ?? {};
+			const debug = raw.debug === true;
+			nekoVueDebug(debug, "recreate:enter", {
+				gen,
+				modeRef: modeRef.value,
+				optionsMode: raw.mode !== void 0 ? toValue(raw.mode) : void 0,
+				clientWidth: typeof document !== "undefined" ? document.documentElement.clientWidth : null,
+				innerHeight: typeof window !== "undefined" ? window.innerHeight : null
+			});
+			error.value = null;
+			isReady.value = false;
+			const priorBm = readInstanceBehaviorMode(instance.value);
+			const wasPetGateInstance = petGateSpawnedInstance.value;
+			const petGateClosed = raw.restUntilFirstPetInteraction === true && !petInteractionAwake.value;
+			const leavingPetGate = wasPetGateInstance && petInteractionAwake.value && priorBm === BehaviorMode.StayStill && !petGateClosed;
+			if (instance.value) {
+				instance.value.stop();
+				instance.value.destroy();
+				instance.value = null;
+			}
+			const { autoStart = true, respectReducedMotion: respectMotion = true } = raw;
+			if (respectMotion && prefersReducedMotion()) {
+				if (gen !== mountGen) return;
+				skippedForReducedMotion.value = true;
+				error.value = null;
+				return;
+			}
+			skippedForReducedMotion.value = false;
+			if (wantsAnchorBinding(raw)) {
+				const anchorEl = resolveAnchorElement(raw);
+				if (!isAnchorLaidOutForCreate(anchorEl)) {
+					const r = anchorEl?.getBoundingClientRect();
+					nekoVueDebug(debug, "recreate:defer anchor layout", {
+						hasEl: Boolean(anchorEl),
+						width: r?.width ?? null,
+						height: r?.height ?? null
+					});
+					return;
+				}
+			}
+			const effectiveMode = petGateClosed ? "rest" : modeRef.value;
+			const nekoOpts = buildCreateOptions(raw, petGateClosed);
+			applyBehaviorModeForRecreate(nekoOpts, raw, petGateClosed, priorBm, leavingPetGate);
+			nekoVueDebug(debug, "recreate:createNeko options (payload)", {
+				...nekoOpts,
+				_effectiveMode: effectiveMode,
+				_autoStart: autoStart,
+				_gen: gen,
+				_petGateClosed: petGateClosed
+			});
+			try {
+				const create = await loadNekoRuntime();
+				if (gen !== mountGen) {
+					const stray = create(nekoOpts);
+					stray.stop();
+					stray.destroy();
+					return;
+				}
+				const nekoInstance = create(nekoOpts);
+				if (gen !== mountGen) {
+					nekoInstance.stop();
+					nekoInstance.destroy();
+					return;
+				}
+				instance.value = nekoInstance;
+				const shouldRun = effectiveMode === "follow" && autoStart !== false;
+				if (shouldRun) nekoInstance.start();
+				else nekoInstance.stop();
+				nekoVueDebug(debug, "recreate:instance ready", {
+					shouldRun,
+					startX: nekoOpts.startX,
+					startY: nekoOpts.startY,
+					behaviorMode: nekoOpts.behaviorMode
+				});
+				isReady.value = true;
+				petGateSpawnedInstance.value = petGateClosed;
+			} catch (e) {
+				if (gen !== mountGen) return;
+				error.value = e instanceof Error ? e : new Error(String(e));
+			}
+		}, {
+			flush: "post",
+			immediate: true
+		});
+	});
+	onBeforeUnmount(() => {
+		stopModeWatch?.();
+		stopWakeOptionWatch?.();
+		stopMainWatch?.();
+		mountGen++;
+		if (instance.value) {
+			instance.value.stop();
+			instance.value.destroy();
+			instance.value = null;
+		}
+		isReady.value = false;
+		skippedForReducedMotion.value = false;
+		petInteractionAwake.value = false;
+		petGateSpawnedInstance.value = false;
+	});
+	function setMode(m) {
+		modeRef.value = m;
+	}
+	function destroy() {
+		if (instance.value) {
+			instance.value.stop();
+			instance.value.destroy();
+			instance.value = null;
+		}
+		isReady.value = false;
+	}
+	/**
+	* Sets `mode` to `rest` (stops at the resolved home position after the next internal cycle).
+	* If you pass a reactive `mode` in options, prefer updating that ref instead; it stays in sync via watch.
+	*/
+	function restAtOrigin() {
+		setMode("rest");
+	}
+	/** Sets `mode` to `follow`. */
+	function resumeFollow() {
+		setMode("follow");
+	}
+	return {
+		instance,
+		error,
+		isReady,
+		skippedForReducedMotion,
+		mode: readonly(modeRef),
+		petInteractionAwake: readonly(petInteractionAwake),
+		setMode,
+		restAtOrigin,
+		resumeFollow,
+		destroy
+	};
+}
+//#endregion
+//#region src/vue/NekoPet.ts
+/**
+* Mounts the desktop pet on the client. Renders a minimal hidden root node for Vue; the engine draws
+* **viewport-fixed** on `document` — not as a child of your layout. Placement is **lifecycle + options**
+* (`startX` / `startY`, `startCorner`, `anchorRef` / `anchorSelector`); a true DOM parent for the sprite
+* would require upstream engine changes.
+*/
+var NekoPet_default = defineComponent({
+	name: "NekoPet",
+	props: {
+		speed: Number,
+		fps: Number,
+		behaviorMode: Number,
+		idleThreshold: Number,
+		cursorStandoffPx: Number,
+		allowBehaviorChange: {
+			type: Boolean,
+			default: void 0
+		},
+		behaviorCycle: Array,
+		startX: Number,
+		startY: Number,
+		autoStart: {
+			type: Boolean,
+			default: true
+		},
+		respectReducedMotion: {
+			type: Boolean,
+			default: true
+		},
+		startCorner: String,
+		anchorSelector: String,
+		mode: {
+			type: String,
+			default: "follow"
+		},
+		restUntilFirstPetInteraction: {
+			type: Boolean,
+			default: void 0
+		},
+		debug: {
+			type: Boolean,
+			default: false
+		}
+	},
+	setup(props, { expose }) {
+		const { instance } = useNeko(computed(() => ({
+			speed: props.speed,
+			fps: props.fps,
+			behaviorMode: props.behaviorMode,
+			idleThreshold: props.idleThreshold,
+			cursorStandoffPx: props.cursorStandoffPx,
+			allowBehaviorChange: props.allowBehaviorChange,
+			behaviorCycle: props.behaviorCycle,
+			startX: props.startX,
+			startY: props.startY,
+			autoStart: props.autoStart,
+			respectReducedMotion: props.respectReducedMotion,
+			startCorner: props.startCorner,
+			anchorSelector: props.anchorSelector || void 0,
+			mode: props.mode,
+			restUntilFirstPetInteraction: props.restUntilFirstPetInteraction,
+			debug: props.debug
+		})));
+		expose({ instance });
+		return () => h("span", {
+			class: "neko-vue-root",
+			"aria-hidden": true
+		});
+	}
+});
+//#endregion
+export { useNeko as n, prefersReducedMotion as r, NekoPet_default as t };