# Copilot instructions — AnimationManager

This file gives actionable, repository-specific guidance for AI coding agents working on AnimationManager.

Overview
- Single-process Node.js server: `server/server.js` is the HTTP server and router. It serves static files from `client/` and `admin/` and exposes REST endpoints under `/api/*`.
- UI: `client/` (end-user) and `admin/` (management) are static HTML/JS pages (no build step) loaded by the server.
- Data and assets live in `server/` (modules, `users/`, `avatar/`, `temp/`) and `server/python/` contains matting/AI scripts invoked by server modules.

Quick start (dev on Windows)
- Install server deps: open `server/` and run `npm install` (dependencies in `server/package.json`).
- Start server: from `server/` run `npm start` or run the workspace root `start-server.bat`.
- Server default port: `3000`.

Key files to read before coding
- `server/server.js` — central router, API registration, static file handling, CORS and caching logic.
- `server/package.json` — start script and runtime deps (`sharp`, `sqlite3`, `formidable`, etc.).
- `server/ai-queue.js`, `server/disk.js`, `server/store/store.js`, `server/user.js` — implementation points for AI, storage, store/catalog, and user logic.
- `client/index.html` and `admin/index.html` — demonstrate iframe-based UI structure and pages under `page/`.

Patterns & conventions (explicit)
- Routing: Add new endpoints by editing `server/server.js`. Follow existing style: check `pathname`, branch, call handler modules, then `return`.
- Static file resolution: server decodes URL path segments (`decodeURIComponent`) and maps `/admin/` → `admin/`, other → `client/`, and `/texture|/avatar|/users` → `server/`.
- Cache behavior: image responses set long `Cache-Control` and `ETag` based on `stat` (follow that pattern for image endpoints).
- File paths: endpoints often expect URL-encoded path segments (e.g. `/api/frames/<encoded-folder>`). Use `encodeURIComponent` per-segment when calling.
- Store mutations: when changing store resources, call `storeManager.clearCategoriesCache()` or `storeManager.clearPricesCache()` as appropriate (seen in `server.js`).
- Error handling style: many handlers write simple JSON/text responses and log to console. Keep changes consistent with existing try/catch and `res.writeHead` usage.

Integration & external dependencies
- Native Node modules + npm: `sharp`, `sqlite3`, `ws`, `formidable`, `archiver` (see `server/package.json`).
- Python matting/AI: scripts live in `server/python/` and are invoked by server modules (ensure a Python venv with `pip install -r server/python/requirements.txt` when testing matting locally).
- AI images: generated assets are stored under `server/users/<username>/ai-images` and served via `/api/ai/image?username=...&id=...`.

Developer tips for common tasks
- Add an API route: update `server/server.js` near other `/api/...` handlers, require or delegate to `server/*.js` handler modules.
- Debugging: server logs API calls when `pathname.startsWith('/api/')`. For interactive debugging, run `node --inspect server.js` from `server/` and attach VS Code.
- Static UI changes: edit files under `client/` or `admin/` and reload browser; no build step.

Examples (call sites)
- Pack sprites: `POST /api/pack` handled by `server/zip.js`.
- AI generate: `POST /api/ai/generate` handled by `server/ai-queue.js`; preview/image endpoints are `/api/ai/preview` and `/api/ai/image`.
- Disk upload/list: `server/disk.js` handlers exposed under `/api/disk/*`.

When to ask maintainers / open an issue
- If you need changes to global routing structure rather than a single endpoint (server.js becomes a long file), ask before refactoring.
- If new native dependencies are required (native `npm` modules or Python libs), request permission because CI/deployment may require environment changes.

If anything above is unclear or you want more examples (handler templates, common response shapes, or a suggested VS Code launch config), tell me which part to expand.