Corey Johnson
a8717733ba
- README: API docs, usage example, dev tool instructions - CLAUDE.md: architecture notes on Hono JSX, Pico CSS, implementation details - Image picker now uses Pico's <details> dropdown pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
149 lines
4.4 KiB
Markdown
149 lines
4.4 KiB
Markdown
# tiny-sprites
|
|
|
|
See [README.md](./README.md) for the API and usage documentation.
|
|
|
|
## Architecture
|
|
|
|
### Hono JSX (not React)
|
|
|
|
This project uses Hono's JSX implementation, not React. Key differences:
|
|
|
|
- **Server-side**: `hono/jsx` for the Sprite component (renders to HTML strings)
|
|
- **Client-side**: `hono/jsx/dom` for the dev tool UI (renders to DOM)
|
|
- **No hooks**: The Sprite component is pure server-side JSX with zero client JavaScript. No `useState`, no `useEffect`. The dev tool uses vanilla JS with a simple mutable `state` object and manual DOM updates via `render()` calls.
|
|
|
|
### Dev Tool Styling
|
|
|
|
The dev tool uses [Pico CSS](https://picocss.com) for styling:
|
|
|
|
- Classless styling - semantic HTML gets styled automatically
|
|
- `<details class="dropdown">` for the image picker (native open/close, no JS needed)
|
|
- CSS variables like `var(--pico-primary-background)` for theming
|
|
|
|
### Interesting Implementation Details
|
|
|
|
**CSS Variables in @keyframes**: Instead of generating unique keyframes per sprite, we define one global keyframe that uses CSS custom properties:
|
|
|
|
```css
|
|
@keyframes sprite {
|
|
from { background-position: var(--x) var(--y) }
|
|
to { background-position: var(--ex) var(--y) }
|
|
}
|
|
```
|
|
|
|
Each sprite just sets `--x`, `--y`, `--ex` as inline styles. This avoids `dangerouslySetInnerHTML` entirely.
|
|
|
|
**Frame Detection Algorithm**: The analyzer (`src/dev/analyze.ts`) scans pixel columns to find content regions. It requires a minimum 10px gap between regions to count as separate frames - this handles sprites that have internal empty columns within a frame.
|
|
|
|
**Crop Calculation**: For each frame, we find the bounding box of non-transparent pixels, then union all frames' bounds. This gives a consistent crop that works across all animation frames without the sprite "jumping".
|
|
|
|
**Canvas Pixel Analysis**: We draw the image to a canvas and use `getImageData()` to read pixel alpha values. The alpha byte is at index `(y * width + x) * 4 + 3` in the flat pixel array.
|
|
|
|
---
|
|
|
|
Default to using Bun instead of Node.js.
|
|
|
|
- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
|
|
- Use `bun test` instead of `jest` or `vitest`
|
|
- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
|
|
- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
|
|
- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
|
|
- Use `bunx <package> <command>` instead of `npx <package> <command>`
|
|
- Bun automatically loads .env, so don't use dotenv.
|
|
|
|
## APIs
|
|
|
|
- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
|
|
- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
|
|
- `Bun.redis` for Redis. Don't use `ioredis`.
|
|
- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
|
|
- `WebSocket` is built-in. Don't use `ws`.
|
|
- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
|
|
- Bun.$`ls` instead of execa.
|
|
|
|
## Testing
|
|
|
|
Use `bun test` to run tests.
|
|
|
|
```ts#index.test.ts
|
|
import { test, expect } from "bun:test";
|
|
|
|
test("hello world", () => {
|
|
expect(1).toBe(1);
|
|
});
|
|
```
|
|
|
|
## Frontend
|
|
|
|
Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
|
|
|
|
Server:
|
|
|
|
```ts#index.ts
|
|
import index from "./index.html"
|
|
|
|
Bun.serve({
|
|
routes: {
|
|
"/": index,
|
|
"/api/users/:id": {
|
|
GET: (req) => {
|
|
return new Response(JSON.stringify({ id: req.params.id }));
|
|
},
|
|
},
|
|
},
|
|
// optional websocket support
|
|
websocket: {
|
|
open: (ws) => {
|
|
ws.send("Hello, world!");
|
|
},
|
|
message: (ws, message) => {
|
|
ws.send(message);
|
|
},
|
|
close: (ws) => {
|
|
// handle close
|
|
}
|
|
},
|
|
development: {
|
|
hmr: true,
|
|
console: true,
|
|
}
|
|
})
|
|
```
|
|
|
|
HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
|
|
|
|
```html#index.html
|
|
<html>
|
|
<body>
|
|
<h1>Hello, world!</h1>
|
|
<script type="module" src="./frontend.tsx"></script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
With the following `frontend.tsx`:
|
|
|
|
```tsx#frontend.tsx
|
|
import React from "react";
|
|
import { createRoot } from "react-dom/client";
|
|
|
|
// import .css files directly and it works
|
|
import './index.css';
|
|
|
|
const root = createRoot(document.body);
|
|
|
|
export default function Frontend() {
|
|
return <h1>Hello, world!</h1>;
|
|
}
|
|
|
|
root.render(<Frontend />);
|
|
```
|
|
|
|
Then, run index.ts
|
|
|
|
```sh
|
|
bun --hot ./index.ts
|
|
```
|
|
|
|
For more information, read the Bun API docs in `node_modules/bun-types/docs/**.mdx`.
|