@clawlabz/clawskin 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# ClawSkin Changelog
+
+## [0.2.0] - 2026-03-01
+
+### 重大更新：3/4 RPG 视角 + 移动系统重构 + 独立宠物系统
+
+本次更新解决三个核心问题：角色被家具遮挡、移动不自然、宠物与角色绑定。
+
+---
+
+### 新增
+
+- **独立宠物系统** (`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 标签 |
+
+---
+
+## [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 页面

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Getting Started
+
+1. **Fork** the repo and clone your fork
+2. Create a **feature branch**: `git checkout -b feat/my-feature`
+3. Make your changes
+4. **Test** locally to make sure everything works
+5. **Commit** with a clear message: `git commit -m "feat: add new scene"`
+6. **Push** and open a **Pull Request**
+
+## Commit Convention
+
+We loosely follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` — New feature
+- `fix:` — Bug fix
+- `docs:` — Documentation only
+- `style:` — Formatting, no logic change
+- `refactor:` — Code restructuring
+- `chore:` — Maintenance tasks
+
+## Code Style
+
+- ES Modules (`import/export`)
+- 2-space indentation
+- Single quotes for strings
+- Descriptive variable names
+
+## Reporting Issues
+
+- Use [GitHub Issues](../../issues)
+- Include steps to reproduce
+- Include browser/Node.js version if relevant
+
+## Questions?
+
+Open a [Discussion](../../discussions) or reach out in the issue tracker.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawLabz
+
+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

@@ -0,0 +1,137 @@
+# 🎨 ClawSkin
+
+**Pixel Agent Skin Engine** — Give your AI assistant a face, an office, and a daily life.
+
+A pixel character engine that visualizes AI agent states in real-time. Pure Canvas 2D, zero dependencies, zero build tools.
+
+<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
+
+## 🚀 Quick Start
+
+```bash
+git clone https://github.com/clawlabz/clawskin.git
+cd clawskin
+npm start
+# → http://localhost:3000
+```
+
+Opens the ClawSkin app and auto-connects to your local OpenClaw Gateway (`ws://localhost:18789`).
+
+> **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.
+
+### 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 (see Security below)
+```
+
+## 🏗️ Architecture
+
+```
+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
+```
+
+### 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 💤 |
+
+## 🔒 Security
+
+ClawSkin is designed to run locally as a companion UI. Here are the security considerations:
+
+### Local server (`serve.cjs`)
+
+- **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.
+
+### Browser storage
+
+- **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.
+
+### WebSocket connection
+
+- 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.
+
+## 🔗 Part of the Claw Ecosystem
+
+```
+ClawSkin (you are here)  →  ClawArena  →  ClawGenesis
+   Free / visual hook        Light game      Deep simulation
+```
+
+ClawSkin characters can be reused as avatars in [ClawArena](https://github.com/clawlabz/clawarena) spectating scenes.
+
+## 🤝 Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Ideas for contributions:
+- 🎨 New scenes (bedroom, spaceship, garden...)
+- 👕 New outfit/hairstyle/accessory sprites
+- 🐾 New pet companions
+- 🌐 i18n support
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 ClawLabz

package/docs/ARCHITECTURE.md

@@ -0,0 +1,132 @@
+# ClawSkin 技术架构
+
+## 产品定位
+像素 Agent 皮肤引擎 —— 给 AI 助手一张脸、一间办公室、一段日常。
+
+## 技术栈
+
+| 层面 | 技术 | 说明 |
+|------|------|------|
+| 渲染引擎 | Phaser 3.80 (CDN) | 成熟2D像素游戏引擎，支持动画/粒子/物理 |
+| 前端框架 | 原生 JS + Phaser | 保持轻量，嵌入式组件不需要Vue |
+| 角色系统 | Sprite Sheet (PNG) | 32x32像素，8方向 + 状态动画 |
+| 场景系统 | Tiled Map Editor → JSON | 瓦片地图，可扩展 |
+| 状态同步 | WebSocket / SSE | 连接 OpenClaw Gateway 获取 Agent 状态 |
+| 配置存储 | localStorage + JSON 文件 | 角色配置、场景偏好 |
+| 部署 | 静态文件 (Vercel/Cloudflare Pages) | 零后端，纯前端 |
+
+## 目录结构
+
+```
+clawSkin/
+├── public/
+│   ├── index.html          # 主页面（展示 + 捏脸 + 场景选择）
+│   ├── assets/
+│   │   ├── sprites/        # 角色 sprite sheets
+│   │   │   ├── base/       # 基础身体（不同肤色）
+│   │   │   ├── hair/       # 发型图层
+│   │   │   ├── outfit/     # 服装图层
+│   │   │   ├── accessory/  # 配饰图层（眼镜/帽子/耳机）
+│   │   │   └── pet/        # 宠物伴侣
+│   │   ├── tiles/          # 场景瓦片素材
+│   │   ├── scenes/         # 预设场景 JSON (from Tiled)
+│   │   └── effects/        # 粒子效果（雨/雪/星星/代码雨）
+│   ├── js/
+│   │   ├── game.js         # Phaser Game 主入口
+│   │   ├── scenes/
+│   │   │   ├── OfficeScene.js      # 像素办公室
+│   │   │   ├── HackerScene.js      # 黑客地下室
+│   │   │   ├── StudyScene.js       # 温馨书房
+│   │   │   ├── SpaceScene.js       # 太空站
+│   │   │   ├── CafeScene.js        # 咖啡馆
+│   │   │   ├── ZenScene.js         # 日式禅室
+│   │   │   ├── LabScene.js         # 实验室
+│   │   │   └── CityScene.js        # 像素城市
+│   │   ├── character/
+│   │   │   ├── CharacterBuilder.js # 捏脸系统
+│   │   │   ├── CharacterSprite.js  # 角色精灵渲染
+│   │   │   └── AnimationManager.js # 动画状态机
+│   │   ├── state/
+│   │   │   ├── AgentStateSync.js   # OpenClaw 状态同步
+│   │   │   └── BubbleManager.js    # 对话气泡管理
+│   │   └── ui/
+│   │       ├── CharacterEditor.js  # 捏脸 UI
+│   │       └── ScenePicker.js      # 场景选择器
+│   └── css/
+│       └── style.css
+├── docs/
+│   ├── ARCHITECTURE.md     # 本文件
+│   └── PROGRESS.md         # 进度记录
+└── scripts/
+    └── generate-sprites.js # 精灵图生成工具
+```
+
+## 核心模块设计
+
+### 1. 角色系统 (Character System)
+
+**图层合成**: 角色由多个图层叠加渲染
+```
+Layer 5: 配饰 (accessory) — 眼镜/帽子/耳机
+Layer 4: 发型 (hair)
+Layer 3: 服装 (outfit) — 格子衫/西装/实验服
+Layer 2: 表情 (expression) — 开心/思考/困惑/困倦
+Layer 1: 身体 (body) — 基础像素人形 + 肤色
+Layer 0: 阴影 (shadow)
+```
+
+**角色配置 JSON**:
+```json
+{
+  "id": "agent-001",
+  "name": "二狗",
+  "body": { "type": "default", "skin": "#FFD5C2" },
+  "hair": { "type": "short_messy", "color": "#333333" },
+  "outfit": { "type": "hoodie", "color": "#4A90D9" },
+  "accessory": { "type": "round_glasses" },
+  "pet": { "type": "pixel_cat", "color": "#FF9900" },
+  "expression": "happy"
+}
+```
+
+### 2. 状态联动 (Agent State Sync)
+
+| OpenClaw Agent 状态 | 像素角色行为 | 动画 |
+|---------------------|-------------|------|
+| idle | 坐椅子喝咖啡/发呆/摸猫 | idle_sit, idle_coffee, idle_pet |
+| thinking | 头上思考气泡 "..." | think_bubble |
+| writing | 快速打字,屏幕闪烁 | typing_fast |
+| executing | 走到服务器机柜操作 | walk_to_server, operate |
+| browsing | 盯屏幕,偶尔点击 | browse_scroll |
+| error | 头上❌,沮丧表情 | error_shake |
+| heartbeat | 向窗外挥手 | wave |
+| sleeping | 趴桌子睡觉💤 | sleep_zzz |
+
+**同步协议**: 通过 SSE 或 WebSocket 连接 OpenClaw Gateway
+```
+GET /api/agent/{id}/status → { state: "writing", message: "处理邮件...", since: timestamp }
+WS  /ws/agent/{id}/events → { type: "state_change", state: "thinking", data: {...} }
+```
+
+### 3. 场景系统 (Scene System)
+
+每个场景 = Phaser Scene 子类:
+- 背景层 (tilemap)
+- 家具/物品层 (interactive objects)
+- 角色层 (character sprite)
+- 气泡/UI层 (dialogue bubbles, status icons)
+- 粒子层 (ambient effects: rain, snow, stars, code rain)
+
+## MVP 范围 (Phase 1)
+
+1. ✅ Phaser 3 引擎初始化 + 基础渲染管线
+2. ✅ 3 个场景: 办公室、黑客地下室、咖啡馆
+3. ✅ 基础角色: 3种体型 × 5种发型 × 5种服装 × 3种配饰
+4. ✅ 8种状态动画 (idle/thinking/typing/executing/browsing/error/wave/sleep)
+5. ✅ 对话气泡系统 (打字机效果)
+6. ✅ 模拟状态切换 (Demo模式，无需真实OpenClaw连接)
+7. ✅ 捏脸 UI (HTML overlay)
+8. ✅ 主页: 产品展示 + Demo
+
+---
+*Created: 2026-02-28*

package/docs/PROGRESS.md

@@ -0,0 +1,15 @@
+# ClawSkin 开发进度
+
+## Phase 1 - MVP
+- [ ] Phaser 3 引擎初始化 + 基础渲染
+- [ ] 像素角色精灵系统 (32x32, 图层合成)
+- [ ] 3 个场景: 办公室、黑客地下室、咖啡馆
+- [ ] 8种状态动画
+- [ ] 对话气泡系统
+- [ ] 捏脸 UI
+- [ ] 嵌入式 iframe 页面
+- [ ] Demo 模式（模拟状态切换）
+- [ ] 主页展示
+
+## 开发日志
+- 2026-02-28 23:30 - 项目初始化，架构文档完成

package/docs/ROADMAP.md

@@ -0,0 +1,130 @@
+# ClawSkin Product Roadmap
+
+**Created**: 2026-03-01
+**Status**: In Development
+
+## Vision
+
+ClawSkin is a real-time pixel character visualization for OpenClaw AI agents.
+Two modes of use:
+1. **Local Mode** — Download and open locally, auto-connects to `localhost:18789`
+2. **Online Mode** — Visit clawskin.io/app, enter Gateway URL + Token, connect remotely
+
+## Gateway WS Protocol (Reverse-Engineered from OpenClaw Source)
+
+### Connection Flow
+```
+1. Browser opens WebSocket to Gateway URL (ws://host:18789 or wss://...)
+2. Gateway sends: { type: "event", event: "connect.challenge", payload: { nonce } }
+3. Client sends RPC: { type: "req", id: uuid, method: "connect", params: { auth: { token }, ... } }
+4. Gateway responds: { type: "res", id: uuid, ok: true, payload: { snapshot: {...} } }
+5. Gateway pushes events: { type: "event", event: "chat"|"agent"|"presence", payload: {...} }
+```
+
+### RPC Format
+```json
+// Request
+{ "type": "req", "id": "uuid", "method": "method.name", "params": {} }
+
+// Response
+{ "type": "res", "id": "uuid", "ok": true, "payload": {} }
+```
+
+### Key Methods
+| Method | Purpose |
+|--------|---------|
+| `connect` | Auth + handshake |
+| `status` | Gateway status (uptime, health) |
+| `health` | Health check |
+| `chat.history` | Get chat message history |
+| `chat.send` | Send a message |
+| `sessions.list` | List active sessions |
+| `agent.identity.get` | Get agent name/avatar |
+
+### Real-Time Events
+| Event | Data | Maps To |
+|-------|------|---------|
+| `chat` (state=delta) | Streaming text | → `typing` animation |
+| `chat` (state=final) | Completed response | → `idle` animation |
+| `agent` (stream=tool, phase=start) | Tool call starting | → `executing` animation |
+| `agent` (stream=tool, phase=result) | Tool call done | → `idle` animation |
+| `agent` (stream=lifecycle) | Fallback/model switch | → `thinking` animation |
+
+### Agent State Mapping
+```
+Gateway Event                          → ClawSkin State
+─────────────────────────────────────────────────────
+No active run, idle                    → idle (sitting, coffee, petting cat)
+chat.send received, waiting            → thinking (thought bubble "...")
+chat delta streaming                   → typing (fast keyboard animation)
+tool phase=start (exec/browser/etc)    → executing (walks to server rack)
+tool phase=start (web_fetch/search)    → browsing (staring at screen)
+tool phase=result with error           → error (❌ above head)
+chat state=final                       → idle (back to relaxed)
+No activity for 30min+                 → sleeping (head on desk 💤)
+Heartbeat event                        → waving (waves at window)
+```
+
+## Architecture
+
+```
+clawSkin/
+├── index.html              # Marketing/landing page (existing)
+├── app.html                # ★ Product app page
+├── css/
+│   ├── style.css           # Landing page styles (existing)
+│   └── app.css             # ★ App-specific styles
+├── js/
+│   ├── app/
+│   │   ├── ClawSkinApp.js      # ★ Main app controller
+│   │   ├── GatewayClient.js    # ★ OpenClaw WS protocol client
+│   │   ├── ConnectionPanel.js  # ★ Connect UI (URL/Token input)
+│   │   ├── AgentStateMapper.js # ★ Gateway events → character states
+│   │   └── SettingsManager.js  # ★ localStorage persistence
+│   ├── character/          # (existing) sprite/animation system
+│   ├── scenes/             # (existing) office/hacker/cafe
+│   ├── sprites/            # (existing) procedural generation
+│   ├── state/              # (existing, refactor DemoMode)
+│   └── ui/                 # (existing) editor/picker
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── ROADMAP.md          # This file
+│   └── PROGRESS.md
+└── package.json
+```
+
+## Development Phases
+
+### Phase 1: Gateway Connection (Current)
+- [x] Reverse-engineer OpenClaw WS protocol
+- [ ] Build GatewayClient.js (WS connect, auth, RPC, event handling)
+- [ ] Build AgentStateMapper.js (event → character state)
+- [ ] Build ConnectionPanel.js (URL/Token input + auto-detect)
+- [ ] Build app.html (product page)
+- [ ] Local auto-detection (try localhost:18789 on load)
+- [ ] localStorage persistence (connection settings + character config)
+
+### Phase 2: Polish & UX
+- [ ] Connection status indicator (connected/disconnected/reconnecting)
+- [ ] Agent identity display (name + avatar from Gateway)
+- [ ] Chat activity indicator (show what agent is working on)
+- [ ] Smooth state transitions (don't jump between states)
+- [ ] Mobile responsive app page
+- [ ] HTTPS/WSS guidance for remote connections
+
+### Phase 3: Distribution
+- [ ] Package as OpenClaw Skill (`clawhub install clawskin`)
+- [ ] Deploy landing page to clawskin.io
+- [ ] npm package (`npx clawskin` to run locally)
+- [ ] GitHub Pages for online mode
+
+## Technical Constraints
+
+### HTTPS → WS Security
+- HTTPS pages can only connect to `wss://` (not `ws://`)
+- Exception: `ws://localhost` is allowed from HTTPS (browser whitelist)
+- Remote users need Tailscale Serve (`wss://machine.ts.net`)
+- Local mode (`file://` or local HTTP) has no restrictions
+
+---
+*Last updated: 2026-03-01*

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@clawlabz/clawskin",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Pixel Agent Skin Engine \u2014 Procedural 32\u00d732 character generator with scenes, animations & customization",
+  "keywords": [
+    "pixel",
+    "agent",
+    "skin",
+    "character",
+    "avatar"
+  ],
+  "author": "ClawLabz",
+  "license": "MIT",
+  "homepage": "https://github.com/clawlabz/clawskin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clawlabz/clawskin.git"
+  },
+  "scripts": {
+    "start": "node serve.cjs",
+    "start:silent": "node serve.cjs --no-open"
+  },
+  "bin": {
+    "clawskin": "./serve.cjs"
+  }
+}

package/public/_headers

@@ -0,0 +1,13 @@
+/*
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; connect-src 'self' ws: wss:; img-src 'self' data:; frame-ancestors 'self'
+
+/*.html
+  Cache-Control: no-cache
+
+/js/*
+  Cache-Control: public, max-age=3600
+
+/css/*
+  Cache-Control: public, max-age=3600

package/public/_redirects

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