wobnimo 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,84 @@
+# Wobnimo — guide for AI agents
+
+Wobnimo renders animated mascots in a web app. One engine, ten characters, ten
+emotional states. Use this file to add or wire up a mascot correctly.
+
+## Install
+
+```bash
+npm i wobnimo
+```
+
+No build step? Add one tag instead:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/wobnimo@0.1/dist/wobnimo.js"></script>
+```
+
+## Render it
+
+React / Next.js (add `"use client"` in app-router files):
+
+```tsx
+import { Mascot } from 'wobnimo/react';
+<Mascot character="mochi" state="thinking" style={{ width: 160, height: 160 }} />
+```
+
+Anything else (Vue, Svelte, plain HTML):
+
+```html
+<wobnimo-mascot character="mochi" state="idle"></wobnimo-mascot>
+```
+
+Size it 96–160 px square. Put it where the assistant or chat lives.
+
+## Characters
+
+`volt` (robot), `pip` (songbird), `mochi` (jelly), `boo` (ghost), `inky` (octopus),
+`miso` (plush cat), `tad` (tree frog), `pebble` (penguin), `rex` (baby dino),
+`microduck` (robot duck). Import one to ship only its ~1.2 KB of data:
+`import { mochi } from 'wobnimo/characters/mochi'`.
+
+## States — the whole point
+
+Drive the state from what the app is doing. The ten states and when to use each:
+
+| State | Use it when |
+| --- | --- |
+| `idle` | waiting for the user |
+| `listening` | the user is typing or talking |
+| `thinking` | a request is sent, no reply yet |
+| `speaking` | a reply is streaming in |
+| `working` | running a tool, a build, a long task |
+| `error` | something failed |
+| `celebrating` | a task finished, tests passed |
+| `surprised` | an unexpected event |
+| `sad` | it could not help |
+| `sleeping` | idle for a couple of minutes |
+
+Set the state through the `state` prop/attribute, or `mascot.setState('thinking')`.
+
+## AI chat, one line
+
+Using the Vercel AI SDK? Pass `useChat`'s `status` straight in; the mascot thinks,
+speaks, celebrates and shows errors for you:
+
+```tsx
+const { status } = useChat();
+<Mascot character="mochi" status={status} />
+```
+
+Plain JS with the element: set the `status` attribute to `submitted`, `streaming`,
+`ready` or `error`.
+
+## Rules
+
+- Prefer the `status` prop for chat UIs; otherwise map the app's real events to the
+  states above. Don't leave a mascot stuck on `idle`.
+- Unknown character or state names throw at runtime and name the valid ones — read
+  the console if a mascot doesn't appear.
+- Recolour with `palette`, e.g. `palette={{ shell: '#e0457b' }}`; material names are
+  per character.
+- Verify: run the app and confirm the mascot renders and changes state during one chat turn.
+
+Full reference: https://pouryaak.github.io/wobnimo/llms.txt

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pourya Akhbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,150 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<a href="https://pouryaak.github.io/wobnimo/">
+  <picture>
+    <source srcset="https://pouryaak.github.io/wobnimo/media/team.webp" type="image/webp">
+    <img src="https://pouryaak.github.io/wobnimo/media/team.gif" alt="The Wobnimo team: ten animated mascots lined up like a team photo, celebrating in a wave" width="900">
+  </picture>
+</a>
+
+# wobnimo
+
+### Give your app a face.
+
+Ten living mascots on one featherweight animation engine for the web.
+Real 3D, every mood, ~25&nbsp;KB, zero dependencies — and built so an AI agent can wire it up for you.
+
+[![npm](https://img.shields.io/npm/v/wobnimo?color=d9f55c&labelColor=16181d)](https://www.npmjs.com/package/wobnimo)
+[![gzip](https://img.shields.io/badge/one%20mascot-~25%20KB%20gzip-d9f55c?labelColor=16181d)](https://pouryaak.github.io/wobnimo/)
+[![zero deps](https://img.shields.io/badge/dependencies-0-d9f55c?labelColor=16181d)](https://www.npmjs.com/package/wobnimo?activeTab=dependencies)
+[![license](https://img.shields.io/npm/l/wobnimo?color=d9f55c&labelColor=16181d)](./LICENSE)
+
+**[▶ Live playground](https://pouryaak.github.io/wobnimo/)** · **[Quickstart](#add-one-in-10-seconds)** · **[For AI agents](#for-ai-agents)**
+
+</div>
+
+---
+
+Chatbots, copilots and apps feel alive when something on screen reacts. Wobnimo gives you a
+character that **thinks while it works, talks while it streams, and celebrates when it's done** —
+in a tag you drop anywhere, with no build step and nothing to configure.
+
+## Add one in 10 seconds
+
+No build, no npm, no framework. Two lines in any HTML page:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/wobnimo@0.1/dist/wobnimo.js"></script>
+
+<wobnimo-mascot character="mochi" state="thinking"></wobnimo-mascot>
+```
+
+That's it — a living mascot is on your page. [Try every character and mood in the playground →](https://pouryaak.github.io/wobnimo/)
+
+## Meet the team
+
+**Volt** the LED robot · **Pip** the songbird · **Mochi** the jelly · **Boo** the ghost · **Inky** the octopus ·
+**Miso** the plush cat · **Tad** the tree frog · **Pebble** the penguin · **Rex** the baby dino · **Microduck** the robot duck.
+
+Each has its own body, surface and personality, and every one of them plays all ten moods.
+Recolour any of them to match your brand, or write your own as plain data.
+
+## Give your AI a face
+
+This is the part that matters. An assistant that just spins a loader feels like a machine.
+Wire a mascot to what your app is doing and it feels like someone is in there.
+
+<div align="center">
+<img src="https://pouryaak.github.io/wobnimo/media/moods.png" alt="Mochi in six moods: listening, thinking, speaking, working, celebrating, sleeping" width="900">
+</div>
+
+Using the [Vercel AI SDK](https://ai-sdk.dev)? It's **one prop** — the mascot thinks, speaks,
+celebrates and shows errors for you:
+
+```tsx
+import { Mascot } from 'wobnimo/react';
+
+const { status } = useChat();
+
+<Mascot character="mochi" status={status} />
+```
+
+The ten states map straight onto what an app or agent actually does:
+
+| State | Show it when | | State | Show it when |
+| --- | --- | --- | --- | --- |
+| `idle` | waiting for the user | | `working` | running a tool or long task |
+| `listening` | the user is typing | | `error` | something failed |
+| `thinking` | request sent, no reply yet | | `celebrating` | a task finished |
+| `speaking` | a reply is streaming | | `surprised` | an unexpected event |
+| `sleeping` | idle for a while | | `sad` | it couldn't help |
+
+## For AI agents
+
+Wobnimo is built to be installed *by* an agent. On the [playground](https://pouryaak.github.io/wobnimo/),
+every character has a **Copy for agent** button: it copies one self-contained prompt that tells any
+agent (Claude Code, Cursor, Copilot, v0…) exactly what to install and how to wire the mascot to your
+app's real events. Paste it, and it's done.
+
+Prefer to point your agent at the docs? Everything is at
+**[pouryaak.github.io/wobnimo/llms.txt](https://pouryaak.github.io/wobnimo/llms.txt)**, and the package
+ships an `AGENTS.md` so an agent inspecting `node_modules/wobnimo` already knows the rules.
+
+## Use it with a bundler
+
+```bash
+npm i wobnimo
+```
+
+**React / Next.js** (`"use client"` in app-router files):
+
+```tsx
+import { Mascot } from 'wobnimo/react';
+
+<Mascot character="volt" state="thinking" style={{ width: 160, height: 160 }} />
+```
+
+**Vanilla JS, Vue, Svelte, anything** — register the element once, then use the tag:
+
+```ts
+import 'wobnimo/element';
+// <wobnimo-mascot character="pip" state="speaking"></wobnimo-mascot>
+```
+
+**Control it in code:**
+
+```ts
+import { mount } from 'wobnimo';
+import { mochi } from 'wobnimo/characters/mochi';
+
+const mascot = mount(document.querySelector('#mascot'), mochi);
+agent.on('status', (s) => mascot.setState(s));   // idle · thinking · speaking · …
+mascot.setPalette({ jelly: '#ff5d8f' });          // recolour live, no rebuild
+```
+
+Import one character (`wobnimo/characters/mochi`, ~1.2 KB) or the whole cast (`wobnimo/characters`) —
+you only ship what you use.
+
+## Why Wobnimo
+
+- **Tiny.** One mascot is ~25 KB gzipped, the whole thing has **zero dependencies**, and no Three.js.
+- **Real, not a sprite.** Characters are signed-distance 3D with studio lighting, so they're crisp at any size and animate from springs, not canned clips.
+- **Characters are data.** A character is plain JSON — parts, materials, bones. Recolour, remix with `variant()`, or write your own.
+- **Drops in anywhere.** A web component for every framework, a first-class React wrapper, and a CDN tag for no-build pages.
+- **Respectful.** Honours `prefers-reduced-motion`, sleeps when off-screen, and shares one WebGL context so a page can hold a whole cast.
+
+## Links
+
+- 🎨 **[Live playground](https://pouryaak.github.io/wobnimo/)** — every character, every mood, copy-paste install
+- 📦 **[npm](https://www.npmjs.com/package/wobnimo)**
+- 🤖 **[llms.txt](https://pouryaak.github.io/wobnimo/llms.txt)** — the whole API for agents
+
+---
+
+<div align="center">
+
+If Wobnimo makes your app smile, **drop a ⭐** — it genuinely helps other people find it.
+
+Built with care. MIT licensed. · Next: a WebGPU renderer, a Rust + WebAssembly core, a visual editor.
+
+</div>

package/dist/characters/boo.d.ts

@@ -0,0 +1,6 @@
+import { C as CharacterSpec } from '../types-PAZ6PnKv.js';
+
+/** A floating ghost with a rippling hem and little arms. */
+declare const boo: CharacterSpec;
+
+export { boo };

package/dist/characters/boo.js

@@ -0,0 +1 @@
+var r={id:"boo",name:"Boo",tagline:"Floats, glows from inside, trails motes, a hem that ripples",accent:"#8a6cf0",frame:{target:.78,radius:.92},bound:{y:.72,radius:.72},motion:{float:.22,hop:.12,squash:.8,snap:.8,talkSquash:.6},glowPool:.55,materials:{ghost:{color:"#eceaff",f0:.04,spec:.5,shininess:30,rim:1.4,sss:.4,sssColor:"#b9a4ff",emit:"#6f52d9",emitStrength:.06},bead:{color:"#1b1430",f0:.06,spec:2.2,shininess:400,rim:.2,gloss:1}},bones:[{name:"body",pivot:[0,0,0],drive:{rx:[["pitch",-0.5]],ry:[["yaw",.7]],rz:[["roll",.6]]},wave:{rz:[.03,.45,0]}},{name:"armL",parent:"body",pivot:[-0.36,.74,.04],drive:{rz:[["flap",-1.2]]},wave:{rz:[.08,.7,0]},jiggle:{axis:[-0.8,-0.6,0],length:.15,freq:2,damping:.2,maxAngle:.7}},{name:"armR",parent:"body",pivot:[.36,.74,.04],drive:{rz:[["flap",1.2]]},wave:{rz:[-0.08,.7,1.6]},jiggle:{axis:[.8,-0.6,0],length:.15,freq:2,damping:.2,maxAngle:.7}}],parts:[{bone:"body",shape:"sphere",at:[0,.88,0],radius:.4,material:"ghost"},{bone:"body",shape:"roundCone",from:[0,.88,0],to:[0,.4,0],r1:.4,r2:.47,material:"ghost"},{bone:"body",shape:"hem",y:.34,amplitude:.045,waves:6,speed:2.4,blend:.05,material:"ghost"},{bone:"armL",shape:"capsule",from:[0,0,0],to:[-0.12,-0.09,.02],radius:.07,blend:.08,material:"ghost"},{bone:"armR",shape:"capsule",from:[0,0,0],to:[.12,-0.09,.02],radius:.07,blend:.08,material:"ghost"}],paints:[{bone:"body",on:["ghost"],kind:"sphere",at:[-0.24,.78,.31],radius:.07,color:"#ffa3c4",soft:.6,opacity:.7},{bone:"body",on:["ghost"],kind:"sphere",at:[.24,.78,.31],radius:.07,color:"#ffa3c4",soft:.6,opacity:.7}],eyes:{kind:"bead",bone:"body",at:[[-0.135,.9,.375],[.135,.9,.375]],radii:[.048,.072,.03],material:"bead"},face:{kind:"mouth",bone:"body",on:["ghost"],at:[0,.77,.38],width:.075,color:"#2a1a4a",tongue:"#ff7fa6"},anchors:{top:{bone:"body",at:[.16,1.2,.1]},mouth:{bone:"body",at:[0,.77,.4]},ear:{bone:"body",at:[-0.42,.92,0]},center:{bone:"body",at:[0,.8,0]}},acting:{idle:{armL:{rz:[0,.1,.7,0]},armR:{rz:[0,.1,.7,1.3]}},thinking:{armR:{ry:-1.1,rz:.9},armL:{rz:.25}},listening:{armL:{rz:-1,rx:-0.35}},speaking:{armL:{rz:[-0.3,.3,1.2,0],rx:[-0.3,.2,.9,0]},armR:{rz:[.3,.3,1.2,1.7],rx:[-0.3,.2,.9,2.2]}},sleeping:{armL:{rz:.4},armR:{rz:-0.4},body:{rz:.08}},working:{armL:{rx:[-0.6,.15,6,0],rz:-0.3},armR:{rx:[-0.6,.15,6,Math.PI],rz:.3}},error:{armL:{rz:[-1,.25,10,0]},armR:{rz:[1,.25,10,1]}},surprised:{armL:{rz:-1.4,rx:-0.4},armR:{rz:1.4,rx:-0.4}},celebrating:{armL:{rz:[-1.6,.3,4,0]},armR:{rz:[1.6,.3,4,Math.PI]}},sad:{armL:{rz:.5},armR:{rz:-0.5},body:{rz:.05}},happy:{armL:{rz:[-1.3,.35,3,0]},armR:{rz:[1.3,.35,3,1.2]}}},fx:{ambient:[{glyph:"mote",anchor:"center",rate:1.3,spread:.5,velocity:[0,.07,0],jitter:.06,wobble:.09,life:[2.2,3.2],size:[.04,.02],color:"#b49cff",glow:true}],happy:[{glyph:"heart",anchor:"top",rate:1.2,spread:.2,velocity:[0,.22,.05],jitter:.12,wobble:.06,life:[1,1.3],size:[.04,.07],color:"#ff86b0"}]}};export{r as boo};

package/dist/characters/index.d.ts

@@ -0,0 +1,12 @@
+export { c as characters, d as defineWobnimoElement } from '../element-DRDEWSGV.js';
+export { boo } from './boo.js';
+export { inky } from './inky.js';
+export { microduck } from './microduck.js';
+export { miso } from './miso.js';
+export { mochi } from './mochi.js';
+export { pebble } from './pebble.js';
+export { pip } from './pip.js';
+export { rex } from './rex.js';
+export { tad } from './tad.js';
+export { volt } from './volt.js';
+import '../types-PAZ6PnKv.js';