# Y.A.R.N. HTML5

A browser remake of **Y.A.R.N.** (Yet Another Random Narrative), the collaborative
story-writing parlor game from GameSpy Arcade, with optional LLM-driven bots.

Players take turns adding one sentence to a shared story, vote for their favourite
entry each round, and score points. The finished story is saved to disk.

## Quick start

```bash
npm install
npm start
# open http://localhost:3000
```

Create or pick a room on the menu, share the `/game/<room>` URL, and the host
can start once at least 3 players (humans + bots) are present.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `PORT` | `3000` | HTTP port |
| `YARN_STORIES_DIR` | `./stories` | Where finished stories are written |
| `OPENAI_API_KEY` | – | Enables LLM bots (any OpenAI-compatible endpoint) |
| `OPENAI_MODEL` | `meta-llama/Llama-3.2-3B-Instruct-Turbo` | Default model |

Bots can also be configured with `bots/llm_config.json` (same shape as the
OpenAI JS client's options, e.g. `{ "apiKey": "...", "baseURL": "...", "model": "..." }`).
Copy `bots/llm_config.example.json` to get started. This file is gitignored.

**If the LLM client cannot be created (no key/config), bots automatically fall
back to `RandomBot`**, so a game always starts. A bot request that fails or
times out degrades to a fallback sentence (or an empty entry) and the game
continues.

## Game rules

- The host picks the round limit, score limit, time per round, bot count and
  starting text. Settings sync live to everyone in the lobby.
- Writing phase: each player submits one sentence (max 280 chars).
- Voting phase: 10 seconds per entry (minimum 15s). You cannot vote for your
  own entry, and empty entries are not voteable.
- Scoring: 1 point per vote received. The single most-voted entry gets +3
  bonus points. On a tie the longest tied entry gets +2 and the others +1.
  **The final round is worth double points.**
- The game ends when a player reaches the score limit, or when the round limit
  is reached (highest score wins). The story is saved automatically.
- The host can skip a stalled writing/voting phase and remove idle players.
  If a player drops, the round advances immediately when everyone remaining
  has submitted/voted.

## Project layout

```
server.js              Express + Socket.IO server and the YarnGame state machine
bots/BotFactory.js     Bot construction (LLM with RandomBot fallback) + unique names
bots/LLMBot.js         OpenAI-compatible bot (write/vote/banter, optional config)
bots/RandomBot.js      Deterministic offline bot
public/menu.html       Room browser, past-story archive, about
public/game.html       Game client (lobby, writing, voting, results, game over)
tests/                 node:test unit + socket integration tests
stories/               Saved stories (gitignored, created on demand)
```

## Tests

```bash
npm test
```

The suite (`node --test tests/*.test.js`) covers:

- `tests/yarn-game.test.js` – scoring (incl. final-round doubling and tie
  breaks), vote validation, phase transitions/timers, reconnection, story
  assembly and persistence.
- `tests/bots.test.js` – factory fallback, unique names, concurrent bot
  writing/voting, invalid bot votes, banter wiring.
- `tests/validation.test.js` – room/player-id sanitisation, settings clamping,
  text cleaning.
- `tests/socket-flow.test.js` – full end-to-end game over real Socket.IO:
  two humans + one bot, writing → voting → results → game over, story saved,
  plus immediate phase advance when the last unsubmitted player disconnects.
- `tests/client-ui.test.js` – loads `game.html` and `menu.html` in jsdom and
  drives the real client code: input preservation, score-limit `0`, refresh
  resync, HUD, own-vote blocking, results table, game-over controls, host
  skip/kick, room list and past-story archive.

### Manual verification checklist

The jsdom suite covers the client logic; a few visual/browser checks are still
worth doing by hand:

1. Open two browser windows on the same room and confirm the live chat, player
   highlight colours and host ★ marker look right.
2. Hover a story segment and confirm the author name appears.
3. On game over, use Download/Copy Story and check the file/clipboard contents.
4. Confirm the results table is readable on a narrow (mobile) viewport.
5. Start a game with 2 humans and 4 bots and confirm the round flow feels right
   (LLM latency, banter in chat, no stalled rounds).