# AGENTS

This file orients coding agents for the test-card repo.
Stack: SvelteKit + Vite + TypeScript + Vitest + ESLint + Prettier.
Package scripts are in `package.json` at repo root.

## Repository layout

- `src/` SvelteKit app source.
- `src/routes/` route and load files.
- `src/lib/` shared code exposed via `$lib`.
- `tests/` Vitest tests and helpers.
- `av-sync/` small Vite + Svelte app for AV sync tools.
- `assets/` generated assets (see `npm run generate-assets`).
- `tests/output/` visual regression artifacts (baseline/current/diff).

## Setup

- Use the existing package manager for scripts; root scripts assume `npm`.
- Install deps with `npm install` if needed.
- Do not add new dependencies without explicit permission.

## Common commands

- Dev server: `npm run dev`.
- Build: `npm run build`.
- Preview build: `npm run preview`.
- Typecheck: `npm run check`.
- Typecheck (watch): `npm run check:watch`.
- Lint: `npm run lint`.
- Format: `npm run format`.
- Generate assets: `npm run generate-assets`.
- AV sync dev server: `npm run av:dev` (runs inside `av-sync/`).
- AV render video: `npm run av:render:video -- <args>`.
- AV render audio: `npm run av:render:audio`.

## Tests

- Test runner: Vitest (no `test` script defined).
- Run all tests once: `npx vitest --run`.
- Run all tests in watch mode: `npx vitest`.
- Run a single file: `npx vitest --run tests/test-card.test.ts`.
- Run a single test by name: `npx vitest --run -t "matches baseline"`.
- Filter by file and name: `npx vitest --run tests/test-card.test.ts -t "matches baseline"`.

### Visual regression test notes

- The test starts its own dev server on port 5888.
- It uses Puppeteer; first run creates `tests/output/testcard-baseline.png`.
- If the baseline changes on purpose, delete the baseline and rerun.
- Diffs are written to `tests/output/testcard-diff.png` when mismatches exist.

## Formatting

- Prettier is the source of truth.
- Tabs for indentation (`useTabs: true`).
- Single quotes (`singleQuote: true`).
- No trailing commas (`trailingComma: none`).
- Max line width 100 (`printWidth: 100`).
- Svelte files use the Svelte parser.

## Linting

- ESLint with TypeScript + Svelte recommended rules and Prettier.
- ESLint ignores `av-sync/**` and all `*.js` files.
- Prefer fixing lint at the source rather than disabling rules.

## TypeScript and SvelteKit

- `tsconfig.json` is strict; keep types accurate.
- Prefer `type` imports: `import type { Foo } from '...'`.
- Keep `export const` config in SvelteKit route files.
- Use `+page.ts`/`+layout.ts` conventions and `$types` imports.
- Use `$lib` alias for shared code inside `src/lib/`.
- Keep server-only logic in `*.server.ts` or server load functions.

## Import style

- Order imports: external packages, internal `$lib` or alias, relative paths.
- Separate type-only imports from runtime imports when it improves clarity.
- Avoid deep relative paths when `$lib` can be used.
- Keep named imports sorted when it improves readability.

## Naming conventions

- Components: `PascalCase.svelte`.
- Functions/variables: `camelCase`.
- Constants: `UPPER_SNAKE_CASE` for true constants.
- Routes: use SvelteKit folder conventions; keep names short and descriptive.
- Files: favor `kebab-case` for non-component utilities.

## Code structure

- Use `const` by default; `let` only when reassigned.
- Prefer `async/await` over `.then()` chains.
- Keep functions small and focused; extract helpers to `src/lib/`.
- Keep Svelte components thin; move heavy logic to modules.

## Error handling

- Throw `Error` objects with clear messages.
- Catch errors only when you can add context or recover.
- Avoid silent failures; log or rethrow with added context.
- For async utilities, reject with `Error` (not strings).

## Testing style

- Use Vitest `describe/it/expect`.
- Keep tests deterministic; avoid time-based flakiness.
- Store artifacts under `tests/output/` only.
- Use helper functions in `tests/utils.ts` for shared setup.

## Styling and UI

- This project uses Svelte; prefer local component styles.
- Keep global styles minimal and intentional.
- If editing fonts or assets, ensure they remain licensed in dependencies.

## Configuration files

- `vite.config.ts` defines the `@assets` alias and inlang plugin.
- `svelte.config.js` uses the static adapter.
- Keep config changes minimal and documented in code when needed.

## Dependency policy

- Do not add, remove, or upgrade deps without explicit permission.
- If you want a new dependency, explain why and ask first.

## Cursor/Copilot rules

- No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found.

## Agent workflow tips

- Prefer small, focused edits with Prettier-friendly formatting.
- Run `npm run lint` and `npx vitest --run` for changes touching logic.
- For UI-only tweaks, at least run `npm run lint`.
- For config changes, run `npm run check`.
- For AV sync changes, validate via `npm run av:dev`.

## When adding new files

- Follow the existing folder structure and naming conventions.
- Update tests if behavior changes.
- Avoid introducing new top-level folders without discussion.

## Logging

- Use `debug` for structured logs in Node utilities.
- Avoid noisy `console.log` in production code.

## Performance

- Avoid unnecessary re-renders in Svelte components.
- Prefer derived values over repeated computation.

## Accessibility

- Keep semantic HTML in Svelte templates.
- Ensure interactive elements are keyboard reachable.

## Data and assets

- Generated assets live under `assets/generated/`.
- Do not edit generated assets by hand.

## Build output

- `npm run build` uses Vite and SvelteKit static adapter.
- `npm run preview` serves the build for verification.

## Notes

- Keep this file updated when commands or conventions change.