SOC OPS Copilot Instructions

Development guidelines for **Soc Ops**, a Social Bingo game with a 5×5 grid and icebreaker questions. Win by marking 5 in a row.

Tech Stack

**Frontend:** React 19 + TypeScript

**Build:** Vite

**Testing:** Vitest

**Styling:** Tailwind CSS v4

**Deploy:** GitHub Pages (auto-deploy on push to `main`)

Pre-commit Checklist

Before committing code, ensure:

1. **Lint passes:** `npm run lint`

2. **Build succeeds:** `npm run build` (TypeScript + Vite)

3. **Tests pass:** `npm run test` (or no new utils added)

Architecture Overview

```

App → (useBingoGame hook)

├── StartScreen

├── GameScreen

│ └── BingoBoard → BingoSquare[]

└── BingoModal

```

**State Management:**

`useBingoGame` hook manages board, marks, localStorage (version: 1), and win detection

Components are stateless and use props-only pattern

Game states: `'start'` | `'playing'` | `'bingo'`

**Win Detection:**

Checks all 12 possible lines (5 rows, 5 cols, 2 diagonals)

Uses `checkBingo()` → `getWinningSquareIds()`

Center square (index 12) = FREE SPACE (always marked)

File Organization

```

src/

types/ # BingoSquareData, GameState, BingoLine

utils/ # generateBoard(), toggleSquare(), checkBingo()

data/ # questions array (24 items), FREE_SPACE constant

hooks/ # useBingoGame (state + persistence)

components/ # App, GameScreen, BingoBoard, BingoSquare, etc.

```

**Conventions:**

Strict TypeScript with null safety

Domain types in `types/index.ts`

Tailwind v4 utilities only (no custom CSS)

Grid layout: `grid grid-cols-5 gap-1 aspect-square`

Board Lifecycle

1. **Generate:** `generateBoard()` shuffles 24 questions via Fisher-Yates, injects FREE SPACE at center (index 12)

2. **Mutate:** `toggleSquare()` immutably flips `isMarked` (non-free squares only)

3. **Persist:** localStorage key `bingo-game-state` with `validateStoredData()` type guard

4. **Detect:** `checkBingo()` runs on each state change → shows modal on win

**localStorage Format:**

```typescript

{

version: number,

gameState: 'start' | 'playing' | 'bingo',

board: BingoSquareData[],

winningLine: BingoLine | null

}

```

Testing Guidelines

**Test Runner:** Vitest with globals enabled

**Setup:** `src/test/setup.ts` (jest-dom matchers + cleanup)

**Coverage:**

Logic: `bingoLogic.test.ts` (80+ tests covering board generation, win detection, localStorage)

Components: No unit tests yet (visual testing only)

**Patterns:**

Test files: `*.test.ts` co-located with source

Mock localStorage: `vi.spyOn(Storage.prototype, 'getItem')`

Test localStorage round-trip for state changes

**Example Test Structure:**

```typescript

describe('checkBingo', () => {

it('detects horizontal bingo', () => {

const board = generateTestBoard([0,1,2,3,4]);

expect(checkBingo(board)).toBeTruthy();

});

```

Common Development Tasks

Add Questions

1. Edit `src/data/questions.ts` (must have 24+ items)

2. No code changes needed (auto-shuffled on board generation)

Modify Win Rules

**Change win logic:** Edit `checkBingo()` in `utils/`

**Change board size:** Update `BOARD_SIZE` and `CENTER_INDEX` constants

Fix Bugs

1. Understand expected behavior from existing tests

2. Add test case reproducing the bug

3. Fix implementation

4. Verify localStorage round-trip still works

Update Styling

Use Tailwind v4 utilities directly in component files

No custom CSS files (all-in utilities)

Development Workflows

```bash

Development server with auto-reload

npm run dev

Production build (TypeScript + Vite → dist/)

npm run build

Run tests (single pass)

npm run test

Lint TypeScript and React code

npm run lint

```

Environment Requirements

**Node.js:** 22+

**Environment Variable:** `VITE_REPO_NAME` (for GitHub Pages base path, auto-set in CI)

Deployment

**Auto-deploy:**

Push to `main` branch → GitHub Actions workflow triggers

Builds app and deploys to GitHub Pages

Production URL: `https://<username>.github.io/<repo-name>/`

Key Implementation Details

**Center Square Behavior:**

Always index 12 on 5×5 board

Always marked (`isMarked: true`)

Clicking it has no effect (`toggleSquare` early returns)

**Board Generation:**

Shuffles 24 questions randomly

Injects FREE_SPACE at index 12

Assigns unique IDs (0-24)

**State Persistence:**

Saves on every toggle and state change

Validates data structure on load

Resets to initial state if validation fails

**Type Safety:**

All functions typed with explicit return types

State shape validated at runtime (localStorage guard)

No `any` types in production code

Error Handling

**localStorage Failures:**

Wrapped in try-catch

Falls back to initial state on parse errors

Logs errors to console (no user-facing messages)

**Build Errors:**

TypeScript errors block build (`tsc -b`)

ESLint errors block CI (must pass lint check)

Best Practices

1. **Keep components pure:** All state in `useBingoGame` hook

2. **Test business logic:** Focus tests on `utils/` functions

3. **Use TypeScript strictly:** No implicit `any`, validate all inputs

4. **Minimize dependencies:** Prefer vanilla solutions over libraries

5. **Document type guards:** Add JSDoc for runtime validators

SOC OPS Copilot Instructions

SOC OPS Copilot Instructions

Tech Stack

Pre-commit Checklist

Architecture Overview

File Organization

Board Lifecycle

Testing Guidelines

Common Development Tasks

Add Questions

Modify Win Rules

Fix Bugs

Update Styling

Development Workflows

Development server with auto-reload

Production build (TypeScript + Vite → dist/)

Run tests (single pass)

Lint TypeScript and React code

Environment Requirements

Deployment

Key Implementation Details

Error Handling

Best Practices

Reviews (0)