npm package: @its-me-mayday/hawkins-control
Description: Lore-accurate Stranger Things themed decision engine for Hawkins RPS style games.
Author: Luca Maggio
Latest version: 1.0.0

# Hawkins Control

<div align="center">

![Nerdy GIF](https://media1.giphy.com/media/v1.Y2lkPTc5MGI3NjExYjY5OG1hM3JoMzYxdTU3ZDc0dDlrYjE0NGY4djEzMDcxZTZtbzV6MSZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/BpZ6GCgB5WJCU/giphy.gif)

</div>

**Lore-accurate Stranger Things battle engine for Rock–Paper–Scissors style games.**  
No UI, no frameworks, just pure TypeScript logic you can drop into any frontend or backend.

You bring the neon red UI and synthwave.  
This package brings **Eleven**, the **Demogorgon**, and **Hawkins Lab** into a clean deterministic triangle of power.

> Eleven beats Demogorgon.  
> Demogorgon tears through Hawkins Lab.  
> Hawkins Lab controls Eleven.  
> Balance is restored. For now.

---

## Features

- 🔺 Lore-perfect Hawkins power triangle
- 🧠 Framework-agnostic, pure TypeScript
- ⚖️ Deterministic `judgeRound` engine
- 🎲 Built-in enemy choice RNG
- 📊 Minimal `Scoreboard` helper
- 🧾 Strongly typed API, ready for React/Vite, Next.js, Node, etc.
- 📜 Verbose logging with `[hawkins-control][...]` prefixes

No JSX, no styling, no spoilers. Only Hawkins logic.

---

## Install

```bash
npm install @its-me-mayday/hawkins-control
# or
pnpm add @its-me-mayday/hawkins-control
# or
yarn add @its-me-mayday/hawkins-control
```

---

## Core Concepts

### Symbols

Available choices:

- `ELEVEN`
- `DEMOGORGON`
- `HAWKINS_LAB`

```ts
import {
  HAWKINS_SYMBOLS,
  isHawkinsSymbol,
  type HawkinsSymbol,
} from "@its-me-mayday/hawkins-control";

HAWKINS_SYMBOLS; // ["ELEVEN", "DEMOGORGON", "HAWKINS_LAB"]
isHawkinsSymbol("ELEVEN"); // true
```

### Rules

The Hawkins triangle:

```ts
import { BEATS, doesBeat } from "@its-me-mayday/hawkins-control";

BEATS;
// ELEVEN -> DEMOGORGON
// DEMOGORGON -> HAWKINS_LAB
// HAWKINS_LAB -> ELEVEN

doesBeat("ELEVEN", "DEMOGORGON"); // true
```

### Judge a Round

```ts
import { judgeRound } from "@its-me-mayday/hawkins-control";

const result = judgeRound("ELEVEN", "DEMOGORGON");

result.outcome;   // "PLAYER" | "ENEMY" | "DRAW"
result.narration; // lore-friendly text, e.g.:
                  // "Eleven unleashes her power and obliterates the Demogorgon."
```

### Enemy Choice

```ts
import { getRandomSymbol } from "@its-me-mayday/hawkins-control";

const enemyChoice = getRandomSymbol();
```

### Scoreboard

```ts
import {
  createInitialScoreboard,
  applyRoundToScoreboard,
} from "@its-me-mayday/hawkins-control";

let scoreboard = createInitialScoreboard();

const round = judgeRound("ELEVEN", getRandomSymbol());
scoreboard = applyRoundToScoreboard(scoreboard, round);

// scoreboard = { wins, losses, draws }
```

---

## Logging

All internals log to `console` with a clear prefix:

- `[hawkins-control][rules] ...`
- `[hawkins-control][judge] ...`
- `[hawkins-control][random] ...`
- `[hawkins-control][scoreboard] ...`

Easy to trace in development, easy to mute or redirect in production.

---

## Usage Ideas

- React/Vite mini-game: **“Hawkins Control”** with synth UI and leaderboard
- Terminal duel tool during standups (who deploys, who brings coffee)
- Easter egg inside a Stranger-Things-themed app
- Teaching example for clean separation of **domain engine** vs **view layer**

---

## Design Philosophy

- Engine-only. No DOM. No CSS. No framework lock-in.
- Data-driven rules, lore-respecting.
- Tiny, readable, testable.
- Swap the skin (UI) without touching the core.

---

## License

MIT.  
Use it. Fork it. Extend Hawkins.