Initial Commit

README.md

@@ -0,0 +1,70 @@
+# HyperPets
+
+Animated pets for [Hyper](https://hyper.is) terminal panes.
+
+The first pass includes:
+
+- one or two pets per pane
+- idle, wander, sleep, cursor-chase, and toy-chase behavior
+- bounded toy spawning with cooldowns
+- lightweight per-pane overlay rendering
+- external cat sprite frames with state transitions between major behaviors
+
+## Install locally during development
+
+1. Put this folder somewhere stable.
+2. Add `hyperpets` to `localPlugins` in your Hyper config.
+
+```js
+module.exports = {
+  config: {
+    hyperPets: {
+      petCount: 1,
+      petTypes: ['cat'],
+      maxToys: 1,
+      toyCooldownMs: 20000,
+      successToyChance: 0.35,
+      walkSpeed: 0.65
+    }
+  },
+  localPlugins: [
+    'hyperpets'
+  ]
+};
+```
+
+On macOS the config file is typically:
+
+`~/Library/Application Support/Hyper/.hyper.js`
+
+Then reload Hyper with `Cmd+R`.
+
+## Config
+
+```js
+hyperPets: {
+  enabled: true,
+  petCount: 1,
+  petTypes: ['cat'],
+  maxToys: 1,
+  toyCooldownMs: 20000,
+  successToyChance: 0.35,
+  chaseCursorChance: 0.04,
+  walkSpeed: 0.65,
+  reducedMotion: false,
+  onlyActivePane: true
+}
+```
+
+## Notes
+
+- Command-success toy spawning currently uses a prompt-return heuristic from terminal output, not shell integration.
+- The plugin is intentionally conservative so it does not flood panes with toys or constant motion.
+- The current animation system uses asset manifests under `assets/pets/`, with only `cat` shipped right now. The loader is generic so additional pet types can be added later without changing behavior logic.
+
+## Asset Pipeline
+
+- Cat frames live in `assets/pets/cat/frames/*.svg`.
+- The cat manifest in `assets/pets/cat.js` maps clips and transitions to those frame files.
+- The renderer reads the SVG files once at startup and swaps them by animation clip at runtime.
+- To add a new pet type later, create another manifest under `assets/pets/` plus a matching frame directory, then register it in `assets/pets/index.js`.