# Tiny Sprites - Design

A CSS-based sprite library for Hono JSX with a dev tool for tuning animations.

## Sprite Component

### API

```tsx
import { Sprite } from 'tiny-sprites'

<Sprite
  src="/warrior-idle.png"
  width={32}
  height={32}
  frames={6}
  frameDuration={100}
/>

// Grid layout
<Sprite
  src="/character.png"
  width={32}
  height={32}
  frames={12}
  columns={4}
  frameDuration={80}
/>
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| src | string | yes | URL to spritesheet |
| width | number | yes | Frame width in pixels |
| height | number | yes | Frame height in pixels |
| frames | number | yes | Total frame count |
| frameDuration | number | yes | Milliseconds per frame |
| columns | number | no | Columns in grid (omit for horizontal strip) |
| class | string | no | Pass-through CSS class |
| style | string | no | Pass-through inline styles |
| playing | boolean | no | Animation state, default true |

### Rendering

The component outputs a `<div>` with inline styles plus a `<style>` block:

```html
<div style="
  width: 32px;
  height: 32px;
  background-image: url('/warrior-idle.png');
  background-size: 192px 32px;
  animation: sprite-abc123 600ms steps(6) infinite;
"></div>

<style>
@keyframes sprite-abc123 {
  from { background-position: 0 0; }
  to { background-position: -192px 0; }
}
</style>
```

Keyframe names are hashed from props to avoid collisions. When `playing={false}`, sets `animation-play-state: paused`.

## Dev Tool

A Bun server for tuning sprite animations.

### Features

- Drag & drop spritesheet files
- Form inputs: width, height, frames, columns, frameDuration
- Live preview
- Copy generated `<Sprite />` code
- Download spritesheet

### Routes

```
GET  /                  → UI
POST /upload            → Accept spritesheet, return temp URL
GET  /sprites/:filename → Serve uploaded spritesheets
```

No database. Files served from temp directory.

## Project Structure

```
tiny-sprites/
├── src/
│   ├── sprite.tsx        # <Sprite /> component
│   ├── hash.ts           # Hash function for keyframe names
│   └── dev/
│       ├── cli.ts        # CLI entry point
│       ├── server.tsx    # Dev server (Bun.serve + Hono)
│       ├── index.tsx     # Dev tool UI page
│       └── preview.tsx   # Live preview component
├── assets/               # Existing sprites
├── docs/plans/
├── package.json
└── tsconfig.json
```

## Package.json

```json
{
  "name": "tiny-sprites",
  "type": "module",
  "exports": {
    ".": "./src/sprite.tsx"
  },
  "bin": {
    "tiny-sprites": "src/dev/cli.ts"
  },
  "scripts": {
    "dev": "bun --hot src/dev/server.tsx",
    "test": "bun test"
  },
  "dependencies": {
    "hono": "^4"
  },
  "devDependencies": {
    "bun-types": "latest"
  }
}
```

## Dependencies

- Bun (runtime)
- Hono (routing + JSX)

No other dependencies.