# Code Style

> Last Updated: 2026-03-31T00:00:00.000Z

## Language & Version

- **TypeScript** 5.x, strict mode enabled
- Target: **ES2020**, module: **ESNext**, module resolution: **bundler**
- `noEmit: true` — Vite handles transpilation; `tsc` is used for type-checking only

## Naming Conventions

| Kind             | Convention    | Examples                                                          |
|------------------|---------------|-------------------------------------------------------------------|
| Types/Interfaces | PascalCase    | `Card`, `GameState`, `PlayerIndex`, `TeamScore`, `ScoreBreakdown` |
| Type aliases     | PascalCase    | `Suit`, `PlayerIndex`                                             |
| Classes          | PascalCase    | `BootScene`, `MenuScene`, `GameScene`                             |
| Functions        | camelCase     | `buildDeck()`, `findCaptures()`, `chooseMove()`, `applyMove()`    |
| Constants        | UPPER_SNAKE   | `PRIMIERA_VALUES`, `SUITS`, `AI_DELAY`, `SCOREBAR_H`             |
| Local variables  | camelCase     | `bestMove`, `capturedCards`, `isScopa`, `afterTable`              |
| Private members  | camelCase     | `this.state`, `this.cardImages`, `this.aiThinking`                |
| Parameters       | camelCase     | `playerIdx`, `captureChoice`, `onComplete`                        |

## Class & Scene Patterns

Scenes extend `Phaser.Scene` and follow the Phaser lifecycle:

```ts
export class BootScene extends Phaser.Scene {
  constructor() {
    super({ key: 'BootScene' });
  }
  preload(): void { /* asset loading */ }
  create(): void { /* scene setup */ }
}
```

Scene registration via `Phaser.Types.Core.GameConfig.scene` array in `main.ts`.

## Indentation & Formatting

- **2-space** indentation
- **Single quotes** for string literals
- No semicolons omission — **semicolons used consistently**
- Trailing commas in multi-line objects/arrays
- `const` preferred; `let` when reassignment is needed; no `var`

## Import Patterns

Named imports from local modules:

```ts
import { Card, GameState, PlayerIndex } from './types';
import { findCaptures, canCapture, calcPrimiera, teamOf } from './engine';
import { chooseMove } from '../game/ai';
```

Default import for Phaser:

```ts
import Phaser from 'phaser';
```

Type-only import for Capacitor config:

```ts
import type { CapacitorConfig } from '@capacitor/cli';
```

Relative paths only (`./`, `../`). No path aliases configured.

## Export Patterns

- **Named exports** for all public symbols (`export function`, `export class`, `export interface`, `export type`, `export const`)
- No default exports except `vite.config.ts` and `capacitor.config.ts` (framework convention)
- Private/internal functions are not exported (`getSubsets`, `calculateScores`, `scoreRound`, `deepClone`)

## Type Annotations

- Explicit return types on exported functions: `(): Card[]`, `(): GameState`, `(): boolean`
- Union types for constrained values: `PlayerIndex = 0 | 1 | 2 | 3`
- String literal unions: `Suit = 'bastoni' | 'coppe' | 'denara' | 'spade'`
- Tuple types for fixed-length arrays: `[Player, Player, Player, Player]`, `[TeamScore, TeamScore]`
- `Record<K, V>` for maps: `PRIMIERA_VALUES: Record<number, number>`

## Comments & Documentation

- **JSDoc** comments on key exported functions (`findCaptures`, `applyMove`)
- Section separators using dashed lines:
  ```ts
  // ---------------------------------------------------------------------------
  // Deck
  // ---------------------------------------------------------------------------
  ```
- `[trueref]` annotations documenting Phaser API provenance
- Inline comments for non-obvious logic (capture rules, AI heuristic weights)
- No auto-generated docs or separate documentation tooling

## Code Examples (from codebase)

### Immutable state update pattern

```ts
export function applyMove(
  state: GameState,
  playerIdx: PlayerIndex,
  card: Card,
  captureChoice?: Card[]
): { nextState: GameState; capture: Capture | null; isScopa: boolean } {
  const state2 = deepClone(state);
  // ... mutations on state2 ...
  return { nextState: state2, capture: ..., isScopa };
}
```

### AI heuristic weighted scoring

```ts
function scoreCapture(...): number {
  let score = 100;           // base for capturing anything
  if (isScopa) score += 500;
  if (settebello) score += 300;
  score += denariCount * 50;
  score += captured.length * 20;
  // ...
  return score;
}
```

### Phaser particle effect

```ts
const e1 = this.add.particles(x, y, 'particle_glow', {
  lifespan: { min: 350, max: 700 },
  speed: { min: 80, max: 280 },
  scale: { start: 0.9, end: 0 },
  tint: color, gravityY: 100, emitting: false,
}).setDepth(25);
e1.explode(count);
```

## Linting & Formatting

No ESLint or Prettier configuration detected. Code style is maintained manually.
TypeScript strict mode provides type-level linting (`strict: true` in `tsconfig.json`).