# Coding Conventions

## Stack

- **Language**: TypeScript (strict mode)
- **Framework**: SvelteKit 5 (Runes mode)
- **Package Manager**: npm
- **Styling**: Tailwind CSS v4
- **Testing**: Vitest (unit/component), Playwright (e2e)
- **Linting**: ESLint + Prettier

## Formatting

- Tabs for indentation, single quotes, trailing commas, semicolons
- Print width: 100 characters
- Import order: node built-ins → third-party → `$app/*` → `$lib/*` → relative
- **Always use absolute imports** — prefer `$lib/...` and `$app/...` over relative paths. The only allowed relative imports are SvelteKit auto-generated route types (`./$types`), which cannot be referenced absolutely
- **Always run Prettier and ESLint** (`npm run format && npx eslint --fix`) before finalizing any code change — never hand-format

## Svelte

- Always use Svelte 5 Runes (`$state`, `$derived`, `$effect`) — no legacy Options API
- Store reactive state in `*.svelte.ts` files under `src/lib/stores/`
- Run `svelte-autofixer` (via MCP) on all new Svelte code before finalizing
- Components should be exported through `index.ts` under `$lib/components/{ComponentName}`

## TypeScript

- No `any` — use `unknown` and narrow explicitly
- Prefer `type` over `interface` for data shapes; use `interface` for extension points
- Co-locate types with the module that owns them
- **Prefer arrow functions over `function` declarations when assigning to a variable** — `function` declarations are fine for class methods; use arrows everywhere else:

  ```ts
  // ✗ function expression as variable
  const handler = function (x: number) {
  	return x * 2;
  };

  // ✓ arrow function
  const handler = (x: number) => x * 2;

  // ✗ top-level named function (not a variable)
  function helper(x: number) {
  	return x * 2;
  }

  // ✓ class method (not a variable)
  class Foo {
  	bar() {
  		return 1;
  	}
  }
  ```

- **Exports go at the bottom of the file** — never use inline `export` on a declaration. Collect all public symbols in a single `export` / `export type` statement at the end:

  ```ts
  // ✗ inline export
  export type Foo = { ... };
  export const bar = () => { ... }

  // ✓ bottom export
  type Foo = { ... };
  const bar = () => { ... }

  export type { Foo };
  export { bar };
  ```