@clawlabz/clawskin 1.0.4 → 1.1.1

package/CHANGELOG.md

@@ -1,98 +1,158 @@
 # ClawSkin Changelog
 
+## [0.3.0] - 2026-03-02
+
+### Agent Chat Panel + Weather System + Interactive Easter Eggs
+
+---
+
+### Added
+
+- **Agent Chat Panel** (`app.html`, `GatewayClient.js`)
+  - Chat panel below character editor for direct messaging with the selected agent
+  - Supports send (`chat.send`) and history loading (`chat.history`)
+  - Real-time streaming display (delta → typing indicator → final message)
+  - Per-agent session isolation via independent sessionKey
+  - Only visible in Live mode; auto-hidden in Demo mode
+
+- **Weather Cycling System** (`OfficeScene.js`, `CafeScene.js`, `HackerScene.js`)
+  - Click window / LED panel to cycle through weather states
+  - Office: ☀️ Sunny → 🌙 Night (moon + stars) → 🌧️ Rain (lightning) → ❄️ Snow
+  - Café: 🌧️ Rain → ☀️ Sunny → ❄️ Snow → 🌫️ Fog
+  - Hacker Den: 💜 Neon → 🔴 Red Alert → 💚 Matrix → 🌑 Blackout
+  - Weather affects global ambience (night darkening, lightning flash, snow on windowsill)
+
+- **Pet Click Reactions** (`Pet.js`, `PetManager.js`)
+  - Click a pet to trigger a random speech bubble (unique phrases per pet type)
+  - Cat: "Purrr~", "💕", "(=^･ω･^=)" / Dog: "Woof!", "*tail wag*", "💖"
+  - Robot: "BOOP", "⚡" / Bird: "Tweet!", "🎵" / Hamster: "Squeak!", "🥜"
+  - Bubbles fade out smoothly; pets pause wandering during interaction
+
+- **Treat Dropping** (`Pet.js`, `PetManager.js`)
+  - Click empty floor to drop a random treat (🍖🦴🐟🥜🌾🍪)
+  - Nearest pet within 200px walks over to eat it
+  - Type-specific reactions: "TREAT!! 🦴", "*chomp*", "Yummy fish!"
+
+- **Interactive Decoration Easter Eggs** (`app.html`)
+  - Click clock → show current time
+  - Click bookshelf → random programmer quote
+  - Click whiteboard → random sprint note
+  - Click arcade cabinet → "INSERT COIN", "HIGH SCORE: 99999", etc.
+  - Click menu board → random café menu item
+  - Click plant → wiggle reaction "🌱 *wiggle*", "🌵 Don't touch!"
+
+### Improved
+
+- **Editor panel layout** — RANDOM button moved to header bar, removed redundant SAVE button
+- **Panel scroll behavior** — Panel itself non-scrollable; chat area fills remaining space with independent scroll
+- **Panel width** 280px → 360px, chat font 5px → 8px for better readability
+- **UI scale threshold** — No zoom below 2560px to prevent bloated HUD on normal screens
+
+### Files Changed
+
+| File | Change | Description |
+|------|--------|-------------|
+| `public/app.html` | Modified | Chat panel CSS/HTML/JS, weather/pet/decoration click handlers, UI scale fix |
+| `public/js/app/GatewayClient.js` | Modified | Added `sendChat()` method |
+| `public/js/pets/Pet.js` | Modified | Added hitTest, react, goToTreat, eatTreat, bubble rendering |
+| `public/js/pets/PetManager.js` | Modified | Added handleClick, dropTreat, treat management |
+| `public/js/scenes/OfficeScene.js` | Modified | 4 weather states + cycleWeather + getWindowRect |
+| `public/js/scenes/CafeScene.js` | Modified | 4 weather states + cycleWeather + getWindowRect |
+| `public/js/scenes/HackerScene.js` | Modified | 4 mood states + cycleWeather + getWindowRect |
+
+---
+
 ## [0.2.0] - 2026-03-01
 
-### 重大更新：3/4 RPG 视角 + 移动系统重构 + 独立宠物系统
+### 3/4 RPG Perspective + Movement Overhaul + Independent Pet System
 
-本次更新解决三个核心问题：角色被家具遮挡、移动不自然、宠物与角色绑定。
+Major update addressing three core issues: characters occluded by furniture, unnatural movement, and pets bound to characters.
 
 ---
 
-### 新增
-
-- **独立宠物系统** (`js/pets/Pet.js`, `js/pets/PetManager.js`)
-  - 宠物不再绑定 Agent，拥有独立的 AI 行为循环
-  - 5 种宠物类型：猫 (walk)、狗 (walk)、机器人 (walk)、鸟 (fly)、仓鼠 (crawl)
-  - 宠物自主移动：随机漫步、找 Agent 蹭腿、找其他宠物互动、原地睡觉
-  - 鸟类飞行正弦波浮动 + 翅膀扇动动画
-  - 仓鼠偶发高速冲刺行为
-  - 宠物配置 localStorage 持久化，默认初始化猫 + 狗
-  - 支持动态增删任意数量的宠物
-
-- **POI 漫游系统** (`AgentSlot.js`)
-  - Agent 空闲时 25% 概率前往 POI（水机、书架、窗户、植物）
-  - 15% 概率走向同事工位进行社交互动
-  - 到达 POI 后显示表情气泡（☕ 🌤️ 📖 👋 🌿）
-  - 漫游范围扩大至全画面区域
-
-- **新宠物精灵** (`SpriteGenerator.js`)
-  - `_drawBird()`: 蓝色身体、橙色喙/爪、2 帧翅膀扇动动画
-  - `_drawHamster()`: 小麦色、粉色鼓腮、圆耳朵、2 帧尾巴摆动
-
-### 改进
-
-- **3/4 俯视视角** — 采用经典 RPG 视角（类 Stardew Valley / Pokemon）
-  - 角色站在桌子后方（Y 值更小 = 画面偏上 = 视觉偏远）
-  - 桌子在角色前方（Y 值更大 = 画面偏下 = 视觉偏近）
-  - 角色上半身完全可见，不再被家具遮挡
-
-- **家具精灵重绘** (`SpriteGenerator.js`)
-  - 桌子：3/4 视角可见桌面顶部 + 正面，木纹细节，48×20px
-  - 显示器 → 笔记本电脑：键盘底座 + 倾斜屏幕，Apple 风格 logo，20×16px
-  - 椅子：可见椅座坐垫 + 椅背 + 脚轮，16×18px
-
-- **三阶段渲染管线** (`ClawSkinApp.js`)
-  - Phase 1: 渲染所有椅子（永远可见）
-  - Phase 2: 按 Y 坐标排序渲染角色（深度排序）
-  - Phase 3: 渲染所有桌面 + 笔记本 + 咖啡杯（永远可见）
-  - Phase 4: 渲染独立宠物
-
-- **平滑移动** (`AgentSlot.js`)
-  - 所有移动使用线性插值 (lerp)，告别瞬移/闪现
-  - 返回工位也是平滑行走，不再直接 teleport
-  - 移动速度提升：0.06~0.08（原 0.04~0.06）
-  - 行走时带自然的正弦波摇晃效果
-
-### 修复
-
-- 修复 Agent 漫游时桌子/椅子消失的问题 — 家具现在永远渲染
-- 修复宠物跟随 Agent 一起瞬移的问题 — 宠物已完全解耦
-- 修复 Agent 漫游后闪现回工位的问题 — 改为平滑走回
-- 修复多 Agent 场景中角色遮挡关系错误 — 引入 Y-sort 深度排序
-
-### 文件变更
-
-| 文件 | 类型 | 说明 |
-|------|------|------|
-| `js/sprites/SpriteGenerator.js` | 修改 | 重绘家具精灵 (3/4 视角)，新增鸟/仓鼠精灵 |
-| `js/scenes/OfficeScene.js` | 修改 | 工位坐标重新计算，renderDesk 渲染顺序调整 |
-| `js/app/ClawSkinApp.js` | 修改 | 三阶段渲染管线，集成 PetManager，Agent 社交引用 |
-| `js/app/AgentSlot.js` | 重写 | lerp 平滑移动，POI 漫游系统，社交行为 |
-| `js/character/CharacterSprite.js` | 修改 | 移除宠物渲染代码 |
-| `js/pets/Pet.js` | **新建** | 独立宠物实体类 |
-| `js/pets/PetManager.js` | **新建** | 宠物集合管理器 |
-| `app.html` | 修改 | 添加 Pet/PetManager script 标签 |
-| `index.html` | 修改 | 添加 Pet/PetManager script 标签 |
-| `app.html` | 修改 | 添加 Pet/PetManager script 标签 |
+### Added
+
+- **Independent Pet System** (`js/pets/Pet.js`, `js/pets/PetManager.js`)
+  - Pets are no longer bound to agents; they have their own AI behavior loop
+  - 5 pet types: Cat (walk), Dog (walk), Robot (walk), Bird (fly), Hamster (crawl)
+  - Autonomous movement: random walk, rub against agents, interact with other pets, nap in place
+  - Bird flight with sine-wave bobbing + wing-flap animation
+  - Hamster occasional speed bursts
+  - Pet config persisted to localStorage; defaults to cat + dog
+
+- **POI Wandering System** (`AgentSlot.js`)
+  - Idle agents have 25% chance to visit POIs (water cooler, bookshelf, window, plant)
+  - 15% chance to walk to a colleague's desk for social interaction
+  - Emoji bubbles on POI arrival (☕ 🌤️ 📖 👋 🌿)
+  - Expanded roaming range to full canvas area
+
+- **New Pet Sprites** (`SpriteGenerator.js`)
+  - `_drawBird()`: Blue body, orange beak/claws, 2-frame wing-flap animation
+  - `_drawHamster()`: Wheat-colored, pink cheek pouches, round ears, 2-frame tail wiggle
+
+### Improved
+
+- **3/4 Top-Down Perspective** — Classic RPG view (Stardew Valley / Pokémon style)
+  - Characters stand behind desks (lower Y = further back visually)
+  - Desks in front of characters (higher Y = closer to viewer)
+  - Upper body fully visible, no longer occluded by furniture
+
+- **Furniture Sprite Redraw** (`SpriteGenerator.js`)
+  - Desk: 3/4 view with visible top surface + front face, wood grain detail, 48×20px
+  - Monitor → Laptop: keyboard base + tilted screen, Apple-style logo, 20×16px
+  - Chair: visible seat cushion + backrest + casters, 16×18px
+
+- **Three-Phase Render Pipeline** (`ClawSkinApp.js`)
+  - Phase 1: Render all chairs (always visible)
+  - Phase 2: Y-sorted character rendering (depth sort)
+  - Phase 3: Render all desks + laptops + cups (always visible)
+  - Phase 4: Render independent pets
+
+- **Smooth Movement** (`AgentSlot.js`)
+  - All movement uses linear interpolation (lerp), no more teleporting
+  - Returning to desk is also a smooth walk
+  - Movement speed increased: 0.06–0.08 (from 0.04–0.06)
+  - Natural sine-wave sway while walking
+
+### Fixed
+
+- Fixed desks/chairs disappearing when agents wander — furniture now always renders
+- Fixed pets teleporting with agents — pets fully decoupled
+- Fixed agents snapping back to desk — now smooth walk-back
+- Fixed character occlusion in multi-agent scenes — introduced Y-sort depth sorting
+
+### Files Changed
+
+| File | Change | Description |
+|------|--------|-------------|
+| `js/sprites/SpriteGenerator.js` | Modified | Redrawn furniture sprites (3/4 view), added bird/hamster sprites |
+| `js/scenes/OfficeScene.js` | Modified | Recalculated workstation coords, adjusted renderDesk order |
+| `js/app/ClawSkinApp.js` | Modified | Three-phase render pipeline, PetManager integration |
+| `js/app/AgentSlot.js` | Rewritten | Lerp smooth movement, POI wandering, social behavior |
+| `js/character/CharacterSprite.js` | Modified | Removed pet rendering code |
+| `js/pets/Pet.js` | **New** | Independent pet entity class |
+| `js/pets/PetManager.js` | **New** | Pet collection manager |
+| `app.html` | Modified | Added Pet/PetManager script tags |
+| `index.html` | Modified | Added Pet/PetManager script tags |
 
 ---
 
 ## [0.1.0] - 2026-02-28
 
-### 初始版本
-
-- 纯 Canvas 2D 渲染，零外部依赖
-- 32×32 像素角色程序化生成（16 帧动画）
-- 5 种肤色、7 种发色、5 种发型、5 种服装类型
-- 4 种配饰：眼镜、帽子、耳机、鸭舌帽
-- 3 种宠物：猫、狗、机器人
-- 3 个场景：办公室、黑客地下室、咖啡馆
-- 8 种状态动画：idle、typing、thinking、executing、browsing、error、sleeping、waving
-- 对话气泡系统
-- 捏脸编辑器 UI
-- Demo 模式（模拟状态切换）
-- 多 Agent 支持（工位自动布局）
-- Gateway WebSocket 连接（OpenClaw 协议）
-- 点击 Agent 打开编辑器
-- localStorage 配置持久化
-- 嵌入式 iframe 页面
+### Initial Release
+
+- Pure Canvas 2D rendering, zero external dependencies
+- 32×32 pixel character procedural generation (16-frame animation)
+- 5 skin tones × 7 hair colors × 5 hairstyles × 5 outfit types
+- 4 accessories: glasses, hat, headphones, cap
+- 3 pets: cat, dog, robot
+- 3 scenes: Office, Hacker Den, Cozy Café
+- 8 state animations: idle, typing, thinking, executing, browsing, error, sleeping, waving
+- Dialogue bubble system with typewriter effect
+- Character editor UI
+- Demo mode (simulated state cycling)
+- Multi-agent support (auto workstation layout)
+- Gateway WebSocket connection (OpenClaw protocol)
+- Click agent to open editor
+- localStorage config persistence
+- Embeddable iframe page

package/README.md

@@ -1,134 +1,90 @@
 # 🎨 ClawSkin
 
-**Pixel Agent Skin Engine** — Give your AI assistant a face, an office, and a daily life.
+**Give your AI agent a pixel life.**
 
-A pixel character engine that visualizes AI agent states in real-time. Pure Canvas 2D, zero dependencies, zero build tools.
+ClawSkin turns your AI assistant into a living pixel character — sitting at a desk, typing code, sipping coffee, petting a cat. Watch your agent work in real-time, or just enjoy the cozy vibes.
+
+<p align="center">
+  <img src="docs/images/screenshot.png" alt="ClawSkin — Pixel agents working in an office" width="720">
+</p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/Canvas_2D-Procedural-blue" alt="Canvas 2D">
-  <img src="https://img.shields.io/badge/JavaScript-ES6+-yellow?logo=javascript&logoColor=white" alt="JavaScript">
   <img src="https://img.shields.io/badge/Dependencies-0-brightgreen" alt="Zero Dependencies">
   <img src="https://img.shields.io/badge/Build-None-brightgreen" alt="Zero Build">
   <img src="https://img.shields.io/github/license/clawlabz/clawskin" alt="License">
 </p>
 
-## ✨ Features
+---
 
-- 🧑‍🎨 **Character Customization** — 5 skin tones × 5 hairstyles × 5 outfits × 4 accessories × 5 pets = 2,500+ combinations
-- 🏠 **3 Scenes** — Office, Hacker Den, Cozy Café (each with ambient animations and particles)
-- 🎬 **8 State Animations** — idle, thinking, typing, executing, browsing, error, wave, sleeping
-- 💬 **Dialogue Bubbles** — Typewriter effect with emoji support
-- 👥 **Multi-Agent** — Display multiple AI agents simultaneously with independent states
-- 🐾 **Pixel Pets** — Cats, dogs, robots, birds, hamsters with autonomous AI behavior
-- 🎮 **Demo Mode** — Runs standalone without any backend connection
-- 📦 **Zero Dependencies** — Pure static files, just Node.js to serve
+## What is this?
 
-## 🚀 Quick Start
+A pixel companion that mirrors what your AI agent is doing — **in real-time**.
 
-```bash
-git clone https://github.com/clawlabz/clawskin.git
-cd clawskin
-npm start
-# → http://localhost:3000
-```
+When your agent thinks, the character scratches its head. When it writes code, the character types furiously. When it browses the web, it stares at the screen. When it sleeps... it sleeps. 💤
 
-Opens the ClawSkin app and auto-connects to your local OpenClaw Gateway (`ws://localhost:18789`).
+> Zero dependencies. Zero build tools. Just pixels.
 
-> **Why `npm start` instead of opening the HTML directly?**
-> Browsers block WebSocket connections from `file://` pages due to origin restrictions.
-> The built-in server runs on `http://localhost` which Gateway accepts. Zero dependencies — just Node.js.
+## ✨ Highlights
 
-### CLI Options
+🧑‍🎨 **Customize Everything** — Mix skin tones, hairstyles, outfits, and accessories. 2,500+ unique looks.
 
-```bash
-npm start                    # Default: localhost:3000, opens browser
-npm start -- --no-open       # Don't open browser
-npm start -- --port 8080     # Custom port
-npm start -- --host 0.0.0.0  # Expose to network (see Security below)
-```
+🏠 **3 Cozy Scenes** — Office, Hacker Den, and Café. Each with ambient weather, particles, and hidden easter eggs.
 
-## 🏗️ Architecture
+🐾 **Pixel Pets** — Cats, dogs, birds, hamsters, and robots that wander around, nap, and react when you click them.
 
-```
-clawSkin/
-├── public/
-│   ├── index.html              # Landing page (demo + customization)
-│   ├── app.html                # Full-screen app (main product)
-│   ├── css/
-│   └── js/
-│       ├── app/                # ClawSkinApp, GatewayClient, Settings
-│       ├── scenes/             # Office / Hacker / Café scenes
-│       ├── character/          # Sprite rendering + animations
-│       ├── sprites/            # Procedural sprite generator
-│       ├── pets/               # Pet entity + manager
-│       ├── state/              # Agent state sync + demo mode
-│       └── ui/                 # Character editor + scene picker
-├── serve.cjs                   # Zero-dependency HTTP server
-└── docs/
-    └── ARCHITECTURE.md         # Detailed architecture doc
-```
+💬 **Chat with Your Agent** — Click an agent to open a chat panel. Talk to them directly from the pixel world.
 
-### Character Layer System
+🌦️ **Weather System** — Click the window to cycle through sunny, rainy, snowy, and night modes.
 
-```
-Layer 5: Accessory  — glasses / hat / headphones
-Layer 4: Hair       — 5 styles with color variants
-Layer 3: Outfit     — hoodie / suit / lab coat / ...
-Layer 2: Expression — happy / thinking / confused / sleepy
-Layer 1: Body       — base 32×32 pixel humanoid + skin tone
-Layer 0: Shadow
-```
-
-### Agent State Mapping
+🎯 **Easter Eggs Everywhere** — Click the clock, bookshelf, plants, arcade machine... everything has a surprise.
 
-| Agent State | Pixel Character Behavior |
-|-------------|-------------------------|
-| `idle`      | Sitting, drinking coffee, petting cat |
-| `thinking`  | Thought bubble "..." |
-| `writing`   | Fast typing, screen flickers |
-| `executing` | Walks to server rack |
-| `browsing`  | Staring at screen, occasional clicks |
-| `error`     | ❌ above head, frustrated expression |
-| `heartbeat` | Waves at window |
-| `sleeping`  | Head on desk 💤 |
+🍖 **Feed Your Pets** — Click the floor to drop a treat. Watch the nearest pet run over and munch it.
 
-## 🔒 Security
-
-ClawSkin is designed to run locally as a companion UI. Here are the security considerations:
+## 🚀 Quick Start
 
-### Local server (`serve.cjs`)
+**One command, zero install:**
 
-- **Binds to `127.0.0.1` by default** — only accessible from your machine. Use `--host 0.0.0.0` explicitly if you need network access.
-- **`/api/config` endpoint** — returns the Gateway URL detected from `~/.openclaw/openclaw.json` for auto-connect convenience. **Auth tokens are never served** by this endpoint; users must enter tokens manually in the UI.
-- **Security headers** — CSP, X-Content-Type-Options, X-Frame-Options, and Referrer-Policy are set on all responses.
+```bash
+npx @clawlabz/clawskin
+```
 
-### Browser storage
+That's it. Opens at `http://localhost:3000` with a live demo.
 
-- **Settings** (Gateway URL, scene choice, character config) are persisted in `localStorage`.
-- **Gateway auth token** is stored in `localStorage` after the user enters it manually. This is standard browser behavior (same as any web app with "remember me"). The token never leaves the browser.
-- **Device identity** — An Ed25519 keypair is generated and stored in `localStorage` for Gateway device pairing. The private key is stored as base64url in plaintext. This is a known tradeoff: `localStorage` is accessible to any JavaScript on the same origin. For a locally-run pixel companion, this is acceptable. If you need stronger protection, use the browser in a dedicated profile.
+<details>
+<summary>Or clone the repo</summary>
 
-### WebSocket connection
+```bash
+git clone https://github.com/clawlabz/clawskin.git
+cd clawskin
+npm start
+```
+</details>
 
-- ClawSkin requests **read-only scopes** (`operator.read`, `operator.events`) from the Gateway — it does not request admin privileges.
-- For remote connections, use `wss://` (e.g. via Tailscale Serve) to encrypt traffic.
+To connect to your AI agent, click **⚡ CONNECT** and enter your [OpenClaw Gateway](https://github.com/anthropics/openclaw) URL.
 
 ## 🔗 Part of the Claw Ecosystem
 
 ```
-ClawSkin (you are here)  →  ClawArena  →  ClawGenesis
-   Free / visual hook        Light game      Deep simulation
+ClawSkin          →  ClawArena        →  ClawGenesis
+Pixel companion      AI battle game      AI civilization
 ```
 
-ClawSkin characters can be reused as avatars in [ClawArena](https://github.com/clawlabz/clawarena) spectating scenes.
+ClawSkin characters can be reused as avatars across the Claw ecosystem.
+
+## 📖 Documentation
+
+- [Technical Architecture](docs/TECHNICAL.md) — render pipeline, state mapping, Gateway protocol
+- [Architecture Overview](docs/ARCHITECTURE.md) — system design
+- [Changelog](CHANGELOG.md) — version history
+- [Roadmap](docs/ROADMAP.md) — what's next
 
 ## 🤝 Contributing
 
-Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions welcome! Ideas:
 
-Ideas for contributions:
 - 🎨 New scenes (bedroom, spaceship, garden...)
-- 👕 New outfit/hairstyle/accessory sprites
+- 👕 New outfits, hairstyles, accessories
 - 🐾 New pet companions
 - 🌐 i18n support
 

package/docs/TECHNICAL.md

@@ -0,0 +1,134 @@
+# ClawSkin Technical Documentation
+
+## Architecture
+
+```
+clawSkin/
+├── public/
+│   ├── index.html              # Landing page (demo + customization)
+│   ├── app.html                # Full-screen app (main product)
+│   └── js/
+│       ├── app/                # ClawSkinApp, GatewayClient, Settings
+│       ├── scenes/             # Office / Hacker / Café scenes
+│       ├── character/          # Sprite rendering + animations
+│       ├── sprites/            # Procedural sprite generator
+│       ├── pets/               # Pet entity + manager
+│       ├── state/              # Agent state sync + demo mode
+│       └── ui/                 # Character editor + scene picker
+├── serve.cjs                   # Zero-dependency HTTP server
+└── docs/
+    └── TECHNICAL.md            # This file
+```
+
+## Character Layer System
+
+```
+Layer 5: Accessory  — glasses / hat / headphones
+Layer 4: Hair       — 5 styles with color variants
+Layer 3: Outfit     — hoodie / suit / lab coat / ...
+Layer 2: Expression — happy / thinking / confused / sleepy
+Layer 1: Body       — base 32×32 pixel humanoid + skin tone
+Layer 0: Shadow
+```
+
+## Agent State Mapping
+
+| Agent State | Pixel Character Behavior |
+|-------------|-------------------------|
+| `idle`      | Sitting, drinking coffee, petting cat |
+| `thinking`  | Thought bubble "..." |
+| `writing`   | Fast typing, screen flickers |
+| `executing` | Walks to server rack |
+| `browsing`  | Staring at screen, occasional clicks |
+| `error`     | ❌ above head, frustrated expression |
+| `heartbeat` | Waves at window |
+| `sleeping`  | Head on desk 💤 |
+
+## Render Pipeline
+
+Three-phase rendering with painter's algorithm (back to front):
+
+1. **Scene Background** — walls, floor, windows, ambient weather effects, decorations
+2. **Workstation Layer** (per agent, Y-sorted):
+   - Chairs (behind character)
+   - Characters (depth-sorted by Y)
+   - Desks + laptops + cups (in front of character)
+3. **Overlay Layer**:
+   - Pets (independent wander, Y-sorted)
+   - Name tags + speech bubbles (always on top)
+
+## Weather System
+
+Each scene supports weather cycling via window/panel click:
+
+| Scene | States |
+|-------|--------|
+| Office | Sunny → Night (moon + stars) → Rain (lightning) → Snow |
+| Café | Rain → Sunny → Snow → Fog |
+| Hacker Den | Neon Purple → Red Alert → Matrix Green → Blackout |
+
+Weather affects: window content, global ambient overlay, particle systems.
+
+## Pet AI Behavior
+
+Decision cycle runs every 3–11 seconds:
+
+| Roll | Action |
+|------|--------|
+| < 0.25 | Walk toward a random agent (rub legs) |
+| < 0.40 | Walk toward another pet |
+| < 0.60 | Random walk within floor bounds |
+| < 0.60 + sleepChance | Sleep in place |
+| else | Idle |
+
+Pet types: Cat (walk), Dog (walk), Robot (walk), Bird (fly + sine bob), Hamster (crawl + speed bursts)
+
+Collision detection against desk obstacles with axis-aligned sliding.
+
+## Gateway Protocol
+
+ClawSkin connects to OpenClaw Gateway via WebSocket (protocol v3).
+
+### Connection Flow
+1. Open WebSocket → receive `connect.challenge` event
+2. Send `connect` RPC with client info + auth token
+3. On success → discover agents via `sessions.list`
+4. Route incoming events by `sessionKey` pattern: `agent:<agentId>:<platform>:...`
+
+### Key RPC Methods
+- `connect` — authenticate and establish session
+- `sessions.list` — discover active agent sessions
+- `chat.send` — send message to agent (requires `idempotencyKey`)
+- `chat.history` — fetch conversation history
+- `agent.identity.get` — get agent metadata
+- `status` / `health` — server status
+
+### Event Types
+- `chat` (states: `delta`, `final`, `aborted`, `error`) — streaming chat responses
+- `agent` (streams: `tool`, `lifecycle`, `compaction`) — agent activity events
+- `presence` — connection status
+
+## Security
+
+### Local Server (`serve.cjs`)
+- Binds to `127.0.0.1` by default — only accessible from your machine
+- `/api/config` returns Gateway URL from `~/.openclaw/openclaw.json` (tokens never served)
+- Security headers: CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy
+
+### Browser Storage
+- Settings persisted in `localStorage` (Gateway URL, scene, character config)
+- Gateway auth token stored in `localStorage` after manual entry
+- Ed25519 device identity keypair for Gateway pairing (base64url in localStorage)
+
+### WebSocket
+- Requests read-only scopes (`operator.read`, `operator.events`)
+- Use `wss://` for remote connections (e.g. via Tailscale Serve)
+
+## CLI Options
+
+```bash
+npm start                    # Default: localhost:3000, opens browser
+npm start -- --no-open       # Don't open browser
+npm start -- --port 8080     # Custom port
+npm start -- --host 0.0.0.0  # Expose to network
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawlabz/clawskin",
-  "version": "1.0.4",
+  "version": "1.1.1",
   "type": "module",
   "description": "Pixel Agent Skin Engine \u2014 Procedural 32\u00d732 character generator with scenes, animations & customization",
   "keywords": [

package/public/_redirects

@@ -1 +0,0 @@
-/ /app.html 302