AGENTS.md

# Repository Guidelines

## Project Structure & Module Organization
- Root: overview in `README.md`.
- `bench-node/`: Node.js CLI benchmark. Source in `src/index.ts`.
- `bench-web/`: Browser benchmark (UI + headless). Source in `src/main.ts` and `src/cli.ts`, HTML in `index.html`.
- Caching: Node uses `.bench-cache/<name>`; Web clears Cache Storage + IndexedDB between runs.

## Build, Test, and Development Commands
- Node (CLI):
  - `cd bench-node && npm i`
  - `npm run bench -- <model> <task> --mode <warm|cold> --repeats <n> [--cache-dir <path>]` (runs benchmark)
  - `npm run build` (type-check via `tsc`)
- Web (UI + CLI):
  - `cd bench-web && npm i && npm run bench:install` (install Playwright browsers)
  - `npm run dev` (start Vite dev server, open http://localhost:5173)
  - `npm run build` (Vite production build)
  - `npm run bench:cli -- <model> <task> --mode <warm|cold> --repeats <n> --device <wasm|webgpu> [--browser <chromium|firefox|webkit>] [--headed true]`
  - Examples:
    - `npm run bench -- Xenova/distilbert-base-uncased feature-extraction --mode warm --repeats 5 --cache-dir .bench-cache/warm`
    - `npm run bench:cli -- Xenova/all-MiniLM-L6-v2 feature-extraction --mode cold --repeats 3 --device wasm`

## Coding Style & Naming Conventions
- Language: TypeScript, ES modules.
- Indentation: 2 spaces; use async/await; keep functions small and composable.
- Filenames: lowercase like `index.ts`, `main.ts`, `cli.ts`; group code under `src/`.
- Exports: prefer named exports from modules; avoid default exports.
- Lint/format: no ESLint/Prettier config in repo—match existing style and run `tsc`/Vite builds to type-check.

## Testing Guidelines
- No unit test framework configured. Validate by running benchmarks and inspecting JSON output for `p50/p90` across `load_ms`, `first_infer_ms`, and `subsequent_infer_ms`.
- Repro tips:
  - Warm (Node): prefetch once, then measure N runs using a dedicated `.bench-cache/<name>`.
  - Cold (Node/Web): ensure cache directory is emptied or browser caches are cleared per run.

## Commit & Pull Request Guidelines
- Commits: short, imperative, scoped when helpful (e.g., `bench-web: add cold mode`). Project history follows this style, e.g., “Add batchsize param”, “Warm/Cold tests, repeated tests”.
- PRs: include purpose, sample commands to reproduce, and a result snippet or screenshot. Link related issues and note any flags (e.g., Chromium `--enable-unsafe-webgpu`) or cache paths used.

## Security & Configuration Tips
- WebGPU: may require flags (`--enable-unsafe-webgpu`) or supported browsers; CLI installs Playwright browsers via `npm run bench:install`.
- Cache safety: Node cold runs delete the target cache dir—use only paths under `.bench-cache/`.