AnimationManager/.github/copilot-instructions.md

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.