oneko 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,8 +1,8 @@
 "use client";
 import { jsx } from "react/jsx-runtime";
-import { useEffect, useRef, useState, useSyncExternalStore } from "react";
-import { m as mountLaserCursor, s as startCatAnimation, g as getSkinSource, l as loadSkinSource, a as applyRuntimeConfig, b as createInitialCatState, O as ONEKO_DEFAULTS, r as readPersistedPosition, o as onCatsHiddenChange, d as areCatsHidden, T as TILE } from "./chunks/vanilla-CUrawvWx.js";
-import { e, c, i, f } from "./chunks/vanilla-CUrawvWx.js";
+import { useEffect, useRef, useState, useSyncExternalStore, useImperativeHandle } from "react";
+import { m as mountLaserCursor, s as startCatAnimation, g as getSkinSource, l as loadSkinSource, a as applyRuntimeConfig, b as createInitialCatState, O as ONEKO_DEFAULTS, d as createCatControls, r as readPersistedPosition, o as onCatsHiddenChange, e as areCatsHidden, T as TILE } from "./chunks/vanilla-BNtPCdx5.js";
+import { f, c, i, h } from "./chunks/vanilla-BNtPCdx5.js";
 function LaserCursor({ zIndex }) {
   useEffect(() => mountLaserCursor(zIndex), [zIndex]);
   return null;
@@ -158,7 +158,18 @@ function Oneko({
   napWhileTyping = ONEKO_DEFAULTS.napWhileTyping,
   followFocus = ONEKO_DEFAULTS.followFocus,
   perchOnHover = ONEKO_DEFAULTS.perchOnHover,
-  pettable = ONEKO_DEFAULTS.pettable
+  pettable = ONEKO_DEFAULTS.pettable,
+  seasonal = ONEKO_DEFAULTS.seasonal,
+  grabbable = ONEKO_DEFAULTS.grabbable,
+  treats = ONEKO_DEFAULTS.treats,
+  timeOfDay = ONEKO_DEFAULTS.timeOfDay,
+  affection = ONEKO_DEFAULTS.affection,
+  onPet,
+  onCatchCursor,
+  onSleep,
+  onToss,
+  onTreat,
+  ref
 }) {
   const hidden = useCatsHidden();
   const motionAllowed = useMotionAllowed() && !hidden;
@@ -200,10 +211,21 @@ function Oneko({
     chase,
     napWhileTyping,
     followFocus,
-    perchOnHover
+    perchOnHover,
+    seasonal,
+    grabbable,
+    treats,
+    timeOfDay,
+    affection,
+    onPet,
+    onCatchCursor,
+    onSleep,
+    onToss,
+    onTreat
   };
   const [initialState] = useState(() => createInitialCatState({ initialPos, ...config }));
   const stateRef = useRef(initialState);
+  useImperativeHandle(ref, () => createCatControls(stateRef), []);
   useCatAnimation({
     enabled: motionAllowed,
     stateRef,
@@ -274,13 +296,13 @@ function RestingCat({
   );
 }
 export {
-  e as ONEKO_SKINS,
+  f as ONEKO_SKINS,
   Oneko,
   areCatsHidden,
   c as createOneko,
   Oneko as default,
   i as isOnekoSkin,
   onCatsHiddenChange,
-  f as setCatsHidden,
+  h as setCatsHidden,
   useCatsHidden
 };

package/dist/solid.js

@@ -1,15 +1,20 @@
 import { onMount, onCleanup, createEffect } from "solid-js";
-import { c as createOneko } from "./chunks/vanilla-CUrawvWx.js";
+import { c as createOneko } from "./chunks/vanilla-BNtPCdx5.js";
 import { createPropsUpdater } from "./adapter.js";
 function Oneko(props) {
   let update;
+  const options = () => {
+    const { ref: _ref, ...rest } = props;
+    return rest;
+  };
   onMount(() => {
     const cat = createOneko();
     update = createPropsUpdater(cat);
-    update({ ...props });
+    update(options());
+    props.ref?.(cat);
     onCleanup(() => cat.destroy());
   });
-  createEffect(() => update?.({ ...props }));
+  createEffect(() => update?.(options()));
   return null;
 }
 export {

package/dist/svelte/Oneko.svelte

@@ -1,16 +1,26 @@
 <script lang="ts">
   import { onMount } from "svelte";
-  import { createOneko, type OnekoOptions } from "../vanilla.js";
+  import { createOneko, type OnekoControls, type OnekoInstance, type OnekoOptions } from "../vanilla.js";
   import { createPropsUpdater } from "../adapter.js";
 
   const props: OnekoOptions = $props();
   let update = $state.raw<ReturnType<typeof createPropsUpdater>>();
+  let cat: OnekoInstance | undefined;
+
+  // bind:this gives the controls: cat.goTo("#pricing"), cat.say("hi").
+  export const goTo: OnekoControls["goTo"] = (target) => cat?.goTo(target) ?? Promise.resolve(false);
+  export const say: OnekoControls["say"] = (text, options) => cat?.say(text, options);
+  export const sit = () => cat?.sit();
+  export const follow = () => cat?.follow();
+  export const pet = () => cat?.pet();
+  export const dropTreat: OnekoControls["dropTreat"] = (x, y) => cat?.dropTreat(x, y);
 
   onMount(() => {
-    const cat = createOneko();
-    update = createPropsUpdater(cat);
+    const created = createOneko();
+    cat = created;
+    update = createPropsUpdater(created);
     update({ ...props });
-    return () => cat.destroy();
+    return () => created.destroy();
   });
 
   $effect(() => update?.({ ...props }));

package/dist/svelte/Oneko.svelte.d.ts

@@ -1,4 +1,4 @@
 import type { Component } from "svelte";
-import type { OnekoOptions } from "../types/packages/oneko/src/vanilla";
-declare const Oneko: Component<OnekoOptions>;
+import type { OnekoControls, OnekoOptions } from "../types/packages/oneko/src/vanilla";
+declare const Oneko: Component<OnekoOptions, OnekoControls>;
 export default Oneko;

package/dist/types/components/oneko.d.ts

@@ -1,6 +1,13 @@
+/**
+ * Installable React component — the classic “cat follows the cursor” idea comes from
+ * oneko.js (MIT): https://github.com/adryd325/oneko.js/
+ */
+import { type Ref } from "react";
+import { type OnekoControls } from "../lib/oneko/controls";
 import { setCatsHidden } from "../lib/oneko/pack";
 import type { CatActivityState, CatLiveState, OnekoProps } from "../lib/oneko/types";
-export type { CatActivityState, CatLiveState, OnekoProps };
+export type { CatActivityState, CatLiveState, OnekoControls, OnekoProps };
+export type { OnekoSeason } from "../lib/oneko/seasons";
 export type { OnekoSkin } from "../lib/oneko/skins";
 export type { OnekoZone } from "../lib/oneko/zones";
 export { setCatsHidden };
@@ -8,4 +15,7 @@ export { setCatsHidden };
 export declare function useCatsHidden(): boolean;
 export default function Oneko({ paused, followCursor, sleepEnabled, bubblePlacement, bubbleScale, soundBasePath, storageKey, zones, zoneAttractionChance, zoneAttractionDuration, skin, spriteSrc, persistPosition, 
 /** One below max so fixed UI can sit above the cat. */
-zIndex, initialPos, speed, scale, opacity, rotationAmount, idleThreshold, meow, onStateChange, freerunChance, freerunDuration, bubbleEnabled, bubbleDisplayFrames, bubbleCooldown, hueRotate, liveStateRef, bubbleChance, followDistance, animationSpeed, bubbleText, volume, laserPointer, reducedMotion, chase, napWhileTyping, followFocus, perchOnHover, pettable, }: OnekoProps): import("react/jsx-runtime").JSX.Element | null;
+zIndex, initialPos, speed, scale, opacity, rotationAmount, idleThreshold, meow, onStateChange, freerunChance, freerunDuration, bubbleEnabled, bubbleDisplayFrames, bubbleCooldown, hueRotate, liveStateRef, bubbleChance, followDistance, animationSpeed, bubbleText, volume, laserPointer, reducedMotion, chase, napWhileTyping, followFocus, perchOnHover, pettable, seasonal, grabbable, treats, timeOfDay, affection, onPet, onCatchCursor, onSleep, onToss, onTreat, ref, }: OnekoProps & {
+    /** Imperative controls: goTo, say, sit, follow, pet, and dropTreat. */
+    ref?: Ref<OnekoControls>;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/lib/oneko/affection.d.ts

@@ -0,0 +1,16 @@
+export type SavedAffection = {
+    version: 1;
+    affection: number;
+    lastVisit: number;
+};
+/** A visit this long after the last one earns a greeting. */
+export declare const GREETING_GAP_MS: number;
+export declare const MAX_AFFECTION = 999;
+export declare function parseAffection(value: unknown): SavedAffection | null;
+export declare function readAffection(key: string): SavedAffection | null;
+export declare function writeAffection(key: string, affection: number, lastVisit?: number): void;
+/** 0 stranger, 1 acquaintance, 2 friend, 3 best friend. */
+export declare function affectionTier(affection: number): 0 | 1 | 2 | 3;
+export declare const GREETINGS: Record<ReturnType<typeof affectionTier>, readonly string[]>;
+/** A greeting for a visitor, or null when they were here a moment ago. */
+export declare function greetingFor(saved: SavedAffection | null, now?: number): string | null;

package/dist/types/lib/oneko/animation/deps.d.ts

@@ -18,4 +18,6 @@ export interface CatAnimationDeps {
     liveStateRef?: {
         current: CatLiveState;
     };
+    /** Seasonal hat drawn on the cat, repositioned with every sprite frame. */
+    hat?: HTMLDivElement;
 }

package/dist/types/lib/oneko/animation/errand-point.d.ts

@@ -0,0 +1,7 @@
+import type { CatRuntimeState, PathPoint } from "../types";
+import type { Errand } from "./play-types";
+/**
+ * Where an errand takes the cat, in viewport coordinates, or null when its element is gone or
+ * off screen. Element targets are re-read every tick, so they follow scrolling and layout.
+ */
+export declare function errandPoint(s: CatRuntimeState, errand: Errand): PathPoint | null;

package/dist/types/lib/oneko/animation/frame.d.ts

@@ -1,2 +1,3 @@
 import type { CatAnimationDeps } from "./deps";
-export declare function createFrameLoop(deps: CatAnimationDeps): () => void;
+import type { CatPlay } from "./play";
+export declare function createFrameLoop(deps: CatAnimationDeps, play?: CatPlay): () => void;

package/dist/types/lib/oneko/animation/play-types.d.ts

@@ -0,0 +1,56 @@
+import type { Treat } from "../treats";
+export type PointLike = {
+    x: number;
+    y: number;
+};
+/** Something the cat goes off to do instead of chasing the cursor. */
+export type Errand = {
+    kind: "goTo";
+    target: Element | PointLike;
+    frames: number;
+    arrived: boolean;
+    resolve?: (arrived: boolean) => void;
+} | {
+    kind: "sit";
+} | {
+    kind: "treat";
+    treat: Treat;
+    frames: number;
+} | {
+    kind: "box";
+    el: Element;
+    frames: number;
+    arrived: boolean;
+} | {
+    kind: "knock";
+    el: Element;
+    frames: number;
+    phase: "approach" | "stare";
+    /** 1 pushes the element to the right, -1 to the left. */
+    direction: 1 | -1;
+};
+export type GrabState = {
+    phase: "held";
+    samples: {
+        x: number;
+        y: number;
+        t: number;
+    }[];
+    startT: number;
+    travel: number;
+} | {
+    phase: "flying";
+    vx: number;
+    vy: number;
+    spin: number;
+    hard: boolean;
+} | {
+    phase: "landed";
+    frames: number;
+};
+/** Multipliers from the visitor's clock; all 1 when timeOfDay is off. */
+export type Mood = {
+    speed: number;
+    freerun: number;
+    idle: number;
+};

package/dist/types/lib/oneko/animation/play.d.ts

@@ -0,0 +1,12 @@
+import type { CatAnimationDeps } from "./deps";
+/** Pet the cat: a purr, a bubble, and a little more affection. */
+export declare function petCat(deps: CatAnimationDeps): void;
+/** Put every knocked-over element back, for when the last cat leaves. */
+export declare function restoreKnocked(): void;
+export declare function createPlay(deps: CatAnimationDeps): {
+    upkeep: () => void;
+    tickGrab: () => boolean;
+    tickErrand: () => void;
+    dispose: () => void;
+};
+export type CatPlay = ReturnType<typeof createPlay>;

package/dist/types/lib/oneko/constants.d.ts

@@ -44,6 +44,7 @@ export declare const DEFAULT_ANIMATION_SPEED = 1;
 export declare const PET_MESSAGES: string[];
 export declare const PET_SOUND_POOL: string[];
 export declare const LASER_CATCH_POOL: string[];
+export declare const HISS_POOL: string[];
 export declare const SOUND_POOLS: Record<CatActivityState, string[]>;
 export declare const KONAMI_SEQUENCE: string[];
 export declare const KONAMI_TARGET: string;

package/dist/types/lib/oneko/controls.d.ts

@@ -0,0 +1,28 @@
+import type { CatRuntimeState } from "./types";
+/** Imperative controls for a running cat, for tours, games, and onboarding. */
+export interface OnekoControls {
+    /**
+     * Walk to an element (or a CSS selector, or a viewport point) and stay there until follow() or
+     * another request. Resolves true on arrival, false if the cat is sent elsewhere first or the
+     * target disappears.
+     */
+    goTo(target: Element | string | {
+        x: number;
+        y: number;
+    }): Promise<boolean>;
+    /** Show a bubble now, even when automatic bubbles are off. Duration defaults to bubbleDisplayFrames. */
+    say(text: string, options?: {
+        duration?: number;
+    }): void;
+    /** Sit where the cat is until follow(). */
+    sit(): void;
+    /** Go back to chasing the cursor after goTo() or sit(). */
+    follow(): void;
+    /** Pet the cat, as if a visitor did. */
+    pet(): void;
+    /** Drop a treat at a viewport point, or at the cursor. Works without the treats option. */
+    dropTreat(x?: number, y?: number): void;
+}
+export declare function createCatControls(stateRef: {
+    current: CatRuntimeState;
+}): OnekoControls;

package/dist/types/lib/oneko/defaults.d.ts

@@ -36,4 +36,9 @@ export declare const ONEKO_DEFAULTS: {
     followFocus: boolean;
     perchOnHover: boolean;
     pettable: boolean;
+    seasonal: NonNullable<OnekoProps["seasonal"]>;
+    grabbable: boolean;
+    treats: boolean;
+    timeOfDay: boolean;
+    affection: boolean;
 };

package/dist/types/lib/oneko/initial-state.d.ts

@@ -1,5 +1,8 @@
 import { type CatRuntimeConfig } from "./runtime-config";
 import type { CatRuntimeState } from "./types";
+type PlayStateFields = Pick<CatRuntimeState, "season" | "grab" | "errand" | "errandCooldown" | "sayRequest" | "bubbleForced" | "petRequest" | "chasingFar" | "mood" | "moodCheckedFrame" | "affection" | "affectionLoaded" | "affectionKey" | "zIndex">;
+/** Fresh state for treats, tosses, errands, seasons, and the API. */
+export declare function defaultPlayState(): PlayStateFields;
 export type InitialCatStateOptions = CatRuntimeConfig & {
     initialPos?: {
         x: number;
@@ -7,3 +10,4 @@ export type InitialCatStateOptions = CatRuntimeConfig & {
     };
 };
 export declare function createInitialCatState(options: InitialCatStateOptions): CatRuntimeState;
+export {};

package/dist/types/lib/oneko/mood.d.ts

@@ -0,0 +1,7 @@
+import type { Mood } from "./animation/play-types";
+export declare const NEUTRAL_MOOD: Mood;
+/**
+ * How a cat feels at a local hour. Cats are crepuscular: most playful at dawn and dusk, drowsy
+ * in the early afternoon, and asleep in the small hours. idle scales the rest time before naps.
+ */
+export declare function moodForHour(hour: number): Mood;

package/dist/types/lib/oneko/pack.d.ts

@@ -2,6 +2,10 @@ import type { CatRuntimeState, PathPoint } from "./types";
 export declare function joinPack(state: CatRuntimeState): () => void;
 /** Where the cat ahead of this one is, or null when it leads (or chases the cursor). */
 export declare function leaderPosition(state: CatRuntimeState): PathPoint | null;
+/** True when no other running cat is closer to a point, so only one cat answers a page event. */
+export declare function isNearestCat(state: CatRuntimeState, point: PathPoint): boolean;
+/** How many cats are running on the page. */
+export declare function packSize(): number;
 /** True when another cat is asleep close enough to curl up next to. */
 export declare function napmateNearby(state: CatRuntimeState): boolean;
 /** Visitor preference, shared by every cat on the site and remembered across visits. */

package/dist/types/lib/oneko/pixel-art.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Inline SVG for pixel art given as rows of characters ("." is transparent), outlined in the
+ * sprite's dark ink so it reads on light and dark pages. The result is one pixel larger on each side.
+ */
+export declare function pixelArtSVG(rows: readonly string[], colors: Record<string, string>): string;

package/dist/types/lib/oneko/play-messages.d.ts

@@ -0,0 +1,8 @@
+export declare const TREAT_MESSAGES: string[];
+export declare const TOSS_SOFT_MESSAGES: string[];
+export declare const TOSS_HARD_MESSAGES: string[];
+export declare const HELD_MESSAGES: string[];
+export declare const BOX_MESSAGES: string[];
+export declare const KNOCK_STARE_MESSAGES: string[];
+export declare const KNOCK_MESSAGES: string[];
+export declare const FOND_PET_MESSAGES: string[];

package/dist/types/lib/oneko/runtime-config.d.ts

@@ -1,8 +1,8 @@
 import type { OnekoZone } from "./zones";
 import type { CatRuntimeState, OnekoProps } from "./types";
-type RuntimeConfigStateFields = Pick<CatRuntimeState, "pausedCfg" | "followCursorCfg" | "sleepEnabledCfg" | "bubblePlacementCfg" | "bubbleScaleCfg" | "soundBasePathCfg" | "currentSpeed" | "scale" | "opacity" | "rotationAmount" | "idleThresholdMs" | "freerunChanceCfg" | "freerunDurationCfg" | "bubbleEnabledCfg" | "bubbleDisplayFramesCfg" | "bubbleCooldownFramesCfg" | "bubbleChanceCfg" | "followDistanceCfg" | "animationSpeedCfg" | "customBubbleText" | "currentRotation" | "enableMeow" | "soundVolumeCfg" | "soundCooldown" | "bubbleTimer" | "bubbleCooldown" | "bubbleVisible" | "lastBubbleMsg" | "laserPointerCfg" | "laserCaught" | "chaseCfg" | "napWhileTypingCfg" | "followFocusCfg" | "perchOnHoverCfg">;
+type RuntimeConfigStateFields = Pick<CatRuntimeState, "pausedCfg" | "followCursorCfg" | "sleepEnabledCfg" | "bubblePlacementCfg" | "bubbleScaleCfg" | "soundBasePathCfg" | "currentSpeed" | "scale" | "opacity" | "rotationAmount" | "idleThresholdMs" | "freerunChanceCfg" | "freerunDurationCfg" | "bubbleEnabledCfg" | "bubbleDisplayFramesCfg" | "bubbleCooldownFramesCfg" | "bubbleChanceCfg" | "followDistanceCfg" | "animationSpeedCfg" | "customBubbleText" | "currentRotation" | "enableMeow" | "soundVolumeCfg" | "soundCooldown" | "bubbleTimer" | "bubbleCooldown" | "bubbleVisible" | "lastBubbleMsg" | "laserPointerCfg" | "laserCaught" | "chaseCfg" | "napWhileTypingCfg" | "followFocusCfg" | "perchOnHoverCfg" | "seasonalCfg" | "grabbableCfg" | "treatsCfg" | "timeOfDayCfg" | "affectionCfg" | "handlers">;
 export declare function defaultRuntimeConfigState(): RuntimeConfigStateFields;
-export type CatRuntimeConfig = Pick<OnekoProps, "paused" | "followCursor" | "sleepEnabled" | "bubblePlacement" | "bubbleScale" | "soundBasePath" | "chase" | "napWhileTyping" | "followFocus" | "perchOnHover"> & {
+export type CatRuntimeConfig = Pick<OnekoProps, "paused" | "followCursor" | "sleepEnabled" | "bubblePlacement" | "bubbleScale" | "soundBasePath" | "chase" | "napWhileTyping" | "followFocus" | "perchOnHover" | "seasonal" | "grabbable" | "treats" | "timeOfDay" | "affection" | "onPet" | "onCatchCursor" | "onSleep" | "onToss" | "onTreat"> & {
     zones?: readonly OnekoZone[];
     zoneAttractionChance?: number;
     zoneAttractionDuration?: number;

package/dist/types/lib/oneko/seasons.d.ts

@@ -0,0 +1,27 @@
+/** Seasonal dress-up: a pixel hat and a few themed thoughts around a holiday. */
+export type OnekoSeason = "halloween" | "winter" | "newYear";
+export declare const ONEKO_SEASONS: readonly ["halloween", "winter", "newYear"];
+export declare function isOnekoSeason(value: unknown): value is OnekoSeason;
+/**
+ * The season on a date in the visitor's local time, or null. Halloween runs Oct 20–31, winter
+ * Dec 18–29, and the new year Dec 30–Jan 2.
+ */
+export declare function seasonForDate(date: Date): OnekoSeason | null;
+/** Which season to dress for: true follows the calendar, a season name forces it, false opts out. */
+export declare function resolveSeason(setting: boolean | OnekoSeason, date?: Date): OnekoSeason | null;
+export declare const SEASON_MESSAGES: Record<OnekoSeason, readonly string[]>;
+/** Hat size in sprite pixels, including the one-pixel outline on every side. */
+export declare const HAT_WIDTH = 13;
+export declare const HAT_HEIGHT = 10;
+/** Inline SVG for a season's hat. */
+export declare function hatSVG(season: OnekoSeason): string;
+/** Offset of the hat's top-left corner within a sprite frame, or null for an unknown frame. */
+export declare function hatOffset(spriteX: number, spriteY: number): {
+    left: number;
+    top: number;
+} | null;
+/**
+ * Where the top of the head is in each 32 × 32 frame, keyed by the sprite offsets used in
+ * constants.ts ("-col,-row"). Values are [x, y] of the hat's bottom center within the frame.
+ */
+export declare const HAT_ANCHORS: Record<string, readonly [number, number]>;

package/dist/types/lib/oneko/treats.d.ts

@@ -0,0 +1,15 @@
+/** A treat on the page, shared by every cat: the first to reach it eats it. */
+export interface Treat {
+    x: number;
+    y: number;
+    el: HTMLDivElement;
+    eaten: boolean;
+}
+export declare function availableTreats(): readonly Treat[];
+/** The uneaten treat closest to a point, or undefined when the floor is clean. */
+export declare function nearestTreat(x: number, y: number, skip?: (treat: Treat) => boolean): Treat | undefined;
+/** Drop a treat at a viewport point. Older treats disappear past five on the floor. */
+export declare function dropTreat(x: number, y: number, zIndex: number): Treat;
+/** Eat a treat. Returns false when another cat got there first. */
+export declare function eatTreat(treat: Treat): boolean;
+export declare function clearTreats(): void;

package/dist/types/lib/oneko/types.d.ts

@@ -1,6 +1,8 @@
 import type { OnekoZone } from "./zones";
 import type { ZoneRuntimeState } from "./zone-runtime";
 import type { OnekoSkin } from "./skins";
+import type { OnekoSeason } from "./seasons";
+import type { Errand, GrabState, Mood } from "./animation/play-types";
 export type CatActivityState = "idle" | "moving" | "sleeping" | "scratchSelf" | "tired" | "alert" | "scratchWallN" | "scratchWallS" | "scratchWallE" | "scratchWallW" | "freerun";
 export type IdleActivityState = Exclude<CatActivityState, "idle" | "moving" | "freerun">;
 export interface CatLiveState {
@@ -96,7 +98,35 @@ export interface OnekoProps {
     perchOnHover?: boolean;
     /** Make the cat a keyboard-reachable "Pet the cat" button. Default false */
     pettable?: boolean;
+    /** Wear a holiday hat around Halloween, the winter holidays, and New Year. A season name forces it. Default true */
+    seasonal?: boolean | OnekoSeason;
+    /** Let visitors pick the cat up and toss it; a click without dragging pets it. Default false */
+    grabbable?: boolean;
+    /** Double-click empty page space to drop a treat the cat runs over to eat. Default false */
+    treats?: boolean;
+    /** Follow the visitor's clock: zoomies at dawn and dusk, sleepy late at night. Default false */
+    timeOfDay?: boolean;
+    /** Remember pets and treats in localStorage and greet returning visitors. Default false */
+    affection?: boolean;
+    /** Called when the cat is petted by keyboard, click, or pet(). */
+    onPet?: (detail: {
+        affection: number;
+    }) => void;
+    /** Called when the cat catches up with the cursor after a chase. */
+    onCatchCursor?: () => void;
+    /** Called when the cat falls asleep. */
+    onSleep?: () => void;
+    /** Called when a visitor throws the cat; speed is in CSS pixels per second. */
+    onToss?: (detail: {
+        speed: number;
+    }) => void;
+    /** Called when the cat eats a treat. */
+    onTreat?: (detail: {
+        affection: number;
+    }) => void;
 }
+/** Event callbacks, kept in the runtime state so they update without a restart. */
+export type OnekoEventHandlers = Pick<OnekoProps, "onPet" | "onCatchCursor" | "onSleep" | "onToss" | "onTreat">;
 export interface ObstacleRect {
     left: number;
     top: number;
@@ -180,4 +210,35 @@ export interface CatRuntimeState {
     perchTarget: PathPoint | null;
     /** Position of the cat this one chases, when chase is "cat" and one exists. */
     leaderTarget: PathPoint | null;
+    seasonalCfg: boolean | OnekoSeason;
+    grabbableCfg: boolean;
+    treatsCfg: boolean;
+    timeOfDayCfg: boolean;
+    affectionCfg: boolean;
+    handlers: OnekoEventHandlers;
+    /** Season currently worn, re-read from the calendar now and then. */
+    season: OnekoSeason | null;
+    /** Being carried, flying after a toss, or catching its breath after landing. */
+    grab: GrabState | null;
+    /** Something the cat set out to do: eat a treat, sit in a box, knock something over, or an API request. */
+    errand: Errand | null;
+    /** Frames until the cat looks for another box or knockable. */
+    errandCooldown: number;
+    /** Text queued by say() or data-oneko-say, shown on the next tick. */
+    sayRequest: {
+        text: string;
+        frames: number;
+    } | null;
+    /** The bubble was requested explicitly and stays up even when automatic bubbles are off. */
+    bubbleForced: boolean;
+    petRequest: boolean;
+    /** Chasing a cursor that was far away; reaching it counts as a catch. */
+    chasingFar: boolean;
+    mood: Mood;
+    moodCheckedFrame: number;
+    affection: number;
+    affectionLoaded: boolean;
+    /** localStorage key for affection, derived from storageKey. */
+    affectionKey: string;
+    zIndex: number;
 }

package/dist/types/lib/oneko/vanilla.d.ts

@@ -1,6 +1,8 @@
+import { type OnekoControls } from "./controls";
 import type { OnekoProps } from "./types";
 export type OnekoOptions = Omit<OnekoProps, "liveStateRef">;
-export interface OnekoInstance {
+export type { OnekoControls };
+export interface OnekoInstance extends OnekoControls {
     /** Merge new options into the running cat; undefined resets one. Engine-level options restart it in place. */
     update(options: OnekoOptions): void;
     /** Remove the cat, bubble, laser, and listeners. Saves the position when persistence is on. */

package/dist/types/packages/oneko/src/solid.d.ts

@@ -1,3 +1,6 @@
-import { type OnekoOptions } from "./vanilla";
-export default function Oneko(props: OnekoOptions): null;
+import { type OnekoControls, type OnekoOptions } from "./vanilla";
+/** Pass ref={(controls) => ...} to get goTo, say, sit, follow, pet, and dropTreat. */
+export default function Oneko(props: OnekoOptions & {
+    ref?: (controls: OnekoControls) => void;
+}): null;
 export type { OnekoOptions } from "./vanilla";

package/dist/types/packages/oneko/src/vanilla.d.ts

@@ -1,5 +1,6 @@
 export { createOneko } from "../../../lib/oneko/vanilla";
-export type { OnekoInstance, OnekoOptions } from "../../../lib/oneko/vanilla";
+export type { OnekoControls, OnekoInstance, OnekoOptions } from "../../../lib/oneko/vanilla";
+export type { OnekoSeason } from "../../../lib/oneko/seasons";
 export { areCatsHidden, setCatsHidden, onCatsHiddenChange } from "../../../lib/oneko/pack";
 export { ONEKO_SKINS, isOnekoSkin } from "../../../lib/oneko/skins";
 export type { OnekoSkin } from "../../../lib/oneko/skins";

package/dist/types/packages/oneko/src/vue.d.ts

@@ -1,5 +1,5 @@
 import { type PropType } from "vue";
-import { type OnekoOptions, type CatActivityState } from "./vanilla";
+import { type CatActivityState, type OnekoOptions } from "./vanilla";
 declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     skin: PropType<OnekoOptions["skin"]>;
     spriteSrc: StringConstructor;
@@ -76,8 +76,39 @@ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropT
         type: BooleanConstructor;
         default: undefined;
     };
+    seasonal: {
+        type: PropType<OnekoOptions["seasonal"]>;
+        default: undefined;
+    };
+    grabbable: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    treats: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    timeOfDay: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    affection: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
 }>, () => null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     stateChange: (_state: CatActivityState) => true;
+    pet: (_detail: {
+        affection: number;
+    }) => true;
+    catchCursor: () => true;
+    sleep: () => true;
+    toss: (_detail: {
+        speed: number;
+    }) => true;
+    treat: (_detail: {
+        affection: number;
+    }) => true;
 }, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     skin: PropType<OnekoOptions["skin"]>;
     spriteSrc: StringConstructor;
@@ -154,20 +185,56 @@ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropT
         type: BooleanConstructor;
         default: undefined;
     };
+    seasonal: {
+        type: PropType<OnekoOptions["seasonal"]>;
+        default: undefined;
+    };
+    grabbable: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    treats: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    timeOfDay: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    affection: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
 }>> & Readonly<{
+    onTreat?: ((_detail: {
+        affection: number;
+    }) => any) | undefined;
     onStateChange?: ((_state: CatActivityState) => any) | undefined;
+    onPet?: ((_detail: {
+        affection: number;
+    }) => any) | undefined;
+    onCatchCursor?: (() => any) | undefined;
+    onSleep?: (() => any) | undefined;
+    onToss?: ((_detail: {
+        speed: number;
+    }) => any) | undefined;
 }>, {
     paused: boolean;
     followCursor: boolean;
     sleepEnabled: boolean;
-    napWhileTyping: boolean;
-    followFocus: boolean;
-    perchOnHover: boolean;
     persistPosition: boolean;
     meow: boolean;
     bubbleEnabled: boolean;
     laserPointer: boolean;
+    napWhileTyping: boolean;
+    followFocus: boolean;
+    perchOnHover: boolean;
     pettable: boolean;
+    seasonal: boolean | import("../../../components/oneko").OnekoSeason | undefined;
+    grabbable: boolean;
+    treats: boolean;
+    timeOfDay: boolean;
+    affection: boolean;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export default _default;
 export type { OnekoOptions } from "./vanilla";