# AGENTS.md — Game Grid

## Stack

- **SvelteKit 2** with **Svelte 5** (runes mode: `$state`, `$derived`, `$props`)
- **TypeScript** (strict), **Tailwind CSS 3**
- **SQLite** via `better-sqlite3` (native module — needs Python/make/g++)
- **bcrypt** (also native), **archiver** for on-the-fly .app zipping
- **Docker** for deployment with multi-stage build and bind-mounted game volumes

## Commands

```bash
npm run dev          # dev server (vite dev)
npm run build        # production build (vite build)
npm run check        # typecheck: runs svelte-kit sync then svelte-check
npm run preview      # preview production build
```

No test, lint, or format scripts exist. No CI.

## Architecture

**Two-tier library**: `GAMES_PATH/public/` (no auth) and `GAMES_PATH/private/` (login required).

**Scanner runs on every layout load** (`src/routes/+layout.server.ts:6`). On first request the scanner walks the file tree, detecting games, series, platforms, cover art, and screenshots — populating the SQLite DB. Database is auto-created and auto-migrated on first access (`src/lib/server/db.ts`).

**Auth**: single shared password (`APP_PASSWORD` env var), bcrypt-hashed at first use, session cookie is HMAC-signed with `SESSION_SECRET`.

**CSRF checkOrigin is disabled** globally in `svelte.config.js` — intentional for local network access.

**Native modules** (`better-sqlite3`, `bcrypt`) require Python 3, `make`, and `g++` for `npm install`. Docker build stage installs these explicitly.

## Important files

| File | Purpose |
|---|---|
| `src/lib/server/db.ts` | DB singleton, schema + migration |
| `src/lib/server/scanner.ts` | Filesystem scanner, game/series detection |
| `src/lib/server/auth.ts` | Session signing, password verification |
| `src/lib/platform.ts` | Platform detection from file extensions |
| `src/routes/+layout.server.ts` | Runs scanner & auth check on every request |
| `src/routes/games/[slug]/+page.server.ts` | Game detail, meta editing, tag actions |
| `src/routes/api/download/[fileId]/+server.ts` | File download, on-the-fly .app zipping |
| `svelte.config.js` | adapter-node, CSRF disabled |
| `docker-compose.yml` | Volume mounts, env vars, port mapping |

## Gotchas

- **Scanner is slow on first load** — it walks every file in both libraries. Plan for this: refreshing while a scan is running will queue another scan.
- **No hot reload for `$env/dynamic/private`** — env var changes require a dev server restart.
- **`.svelte-kit/tsconfig.json` is generated** by `svelte-kit sync` and needed for TypeScript to resolve `$lib` etc. The `check` command runs sync first, but in an IDE you may need to run `npm run dev` once to generate it.
- **Game files are served directly off disk** — paths come from the DB and map to real filesystem paths under `GAMES_PATH`. If bind mounts change, re-scan (hit the app or `POST /api/scan`) to update the DB.
- **`.app` bundles** (macOS) are zipped on-the-fly for download — this is CPU-intensive for large bundles.