# Table-Fidelity Features Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add three physical-table-faithful features to blind chess — broadcast all moderator announcements to both players, a running capture tally, and a client-local phantom-opponent-piece overlay.

**Architecture:** Two increments. Increment 1 (Features 1+2) is server-centric and independently shippable. Increment 2 (Feature 3) is a client-only phantom layer that never touches the server. The zero-leak core (`buildView`, `geometric.ts`) is untouched throughout.

**Tech Stack:** Node 22 + TypeScript, Fastify + `ws`, Svelte 5 (runes), `chess.js`. pnpm workspace `packages/{server,client,shared}`. Tests: `vitest` in `shared` and `server` only — the client has no test harness, so client tasks use `svelte-check` typechecking plus a manual-verification step.

**Spec:** `docs/superpowers/specs/2026-05-18-table-fidelity-features-design.md`

**Conventions for every commit step below:** conventional-commit messages; append the `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>` trailer per repo convention; run `gitea push` immediately after each commit (homelab rule: never leave a commit unpushed).

**Build ordering note:** `packages/server` and `packages/client` resolve `@blind-chess/shared` from its built `dist/`. Whenever a task adds a new export to `shared`, it must run `pnpm --filter @blind-chess/shared build` before downstream typechecks/builds will see it. Build steps are included where needed.

---

## Increment 1 — Features 1 & 2

### Task 1: Widen moderator announcement audiences to `'both'`

Move events and attempted-move errors currently reach only one player. Make every announcement `audience: 'both'` so the moderator panel is a complete shared transcript.

**Files:**
- Modify: `packages/server/src/translator.ts:36-51`
- Modify: `packages/server/src/commit.ts:39-119`
- Test: `packages/server/test/unit/commit-fsm.test.ts` (append)

- [ ] **Step 1: Write the failing tests**

Append these two `it` blocks inside the `describe('hierarchy decision table', ...)` block in `packages/server/test/unit/commit-fsm.test.ts` (after the existing `row 6` test, before the closing `});` of that describe):

```ts
  it('attempted-move announcements are audience: both', () => {
    const r = handleCommit(game, 'w', { from: 'e4' }); // empty square -> no_such_piece
    expect(r.kind).toBe('announce');
    if (r.kind === 'announce') expect(r.announcements[0]!.audience).toBe('both');
  });

  it('applied-move announcements are audience: both', () => {
    const r = handleCommit(game, 'w', { from: 'e2', to: 'e4' });
    expect(r.kind).toBe('applied');
    if (r.kind === 'applied') {
      for (const a of r.announcements) expect(a.audience).toBe('both');
    }
  });
```

- [ ] **Step 2: Run the tests to verify they fail**

Run: `pnpm --filter @blind-chess/server test`
Expected: the two new tests FAIL — `no_such_piece` currently has `audience: 'w'` and `white_moved` currently has `audience: 'b'`, not `'both'`.

- [ ] **Step 3: Change move-event audiences in `translator.ts`**

In `packages/server/src/translator.ts`, replace the block at lines 36-51 (the `// To opponent` comment through the promotion `if`) with:

```ts
  // To both players: the move event itself (Feature 1 — the moderator
  // announces every move aloud; both players hear it).
  if (isKingsideCastle) {
    out.push(announce(`${moverWord}_castled_kingside` as ModeratorText, 'both', ply));
  } else if (isQueensideCastle) {
    out.push(announce(`${moverWord}_castled_queenside` as ModeratorText, 'both', ply));
  } else if (isCap && isEp) {
    out.push(announce(`${moverWord}_moved_captured_ep` as ModeratorText, 'both', ply));
  } else if (isCap) {
    out.push(announce(`${moverWord}_moved_captured` as ModeratorText, 'both', ply));
  } else {
    out.push(announce(`${moverWord}_moved` as ModeratorText, 'both', ply));
  }

  if (isProm) {
    out.push(announce(`${moverWord}_promoted` as ModeratorText, 'both', ply, { promotedTo: move.promotion }));
  }
```

(The `opp` variable is still used below to derive `oppWord` for the `*_in_check` announcement — leave it.)

- [ ] **Step 4: Change attempted-move audiences in `commit.ts`**

In `packages/server/src/commit.ts`, replace the `announceWith` function (lines 110-119) with:

```ts
function announceWith(
  game: Game,
  text: 'no_such_piece' | 'no_legal_moves' | 'wont_help' | 'illegal_move',
): CommitResult {
  const ply = game.chess.history().length;
  // Feature 1: attempted moves are announced to both players.
  const a = announce(text, 'both', ply);
  game.announcements.push(a);
  return { kind: 'announce', announcements: [a] };
}
```

Then update its four call sites in `handleCommit` to drop the now-removed `color` argument:
- `return announceWith(game, 'no_such_piece', color);` → `return announceWith(game, 'no_such_piece');`
- `return announceWith(game, 'no_legal_moves', color);` → `return announceWith(game, 'no_legal_moves');`
- `return announceWith(game, 'wont_help', color);` → `return announceWith(game, 'wont_help');`
- `return announceWith(game, 'illegal_move', color);` → `return announceWith(game, 'illegal_move');`

- [ ] **Step 5: Run the tests to verify they pass**

Run: `pnpm --filter @blind-chess/server test`
Expected: PASS — all server tests pass, including the two new ones. The existing `commit-fsm` and integration tests still pass (their predicates check announcement `.text`, not `.audience`, and opponents still receive move events).

- [ ] **Step 6: Typecheck**

Run: `pnpm --filter @blind-chess/server typecheck`
Expected: PASS — no unused-variable error (`color` is still used elsewhere in `handleCommit`).

- [ ] **Step 7: Commit**

```bash
git add packages/server/src/translator.ts packages/server/src/commit.ts packages/server/test/unit/commit-fsm.test.ts
git commit -m "feat(server): moderator announces every move and attempt to both players"
gitea push
```

---

### Task 2: Suppress the bot's intermediate retry rejections

With attempted moves now `'both'`, the Casual bot's blind-mode retry loop would broadcast up to 25 rejection announcements per turn as search churn. Discard the bot's own intermediate rejections; only its final committed move is announced.

**Files:**
- Modify: `packages/server/src/bot/driver.ts:152-189`
- Test: `packages/server/test/unit/bot/driver.test.ts` (append)

- [ ] **Step 1: Write the failing test**

Append this `it` block inside the `describe('BotDriver', ...)` block in `packages/server/test/unit/bot/driver.test.ts` (after the `retry on illegal_move` test):

```ts
  it('suppresses the bot intermediate retry rejection from the moderator log', async () => {
    // Pinned-bishop position: first action is rejected (wont_help), second
    // is a legal king move. The wont_help must NOT survive in announcements.
    const fen = '4k2K/4b3/8/8/8/8/8/4R3 b - - 0 1';
    game = makeGame({ fen });
    brain = new StubBrain();
    driver = new BotDriver({ game, brain, color: 'b' });
    await driver.init();
    brain.enqueue(
      { type: 'commit', from: 'e7', to: 'd6' }, // rejected: wont_help
      { type: 'commit', from: 'e8', to: 'f8' }, // legal king move
    );
    await driver.onStateChange();
    const texts = game.announcements.map((a) => a.text);
    expect(texts).not.toContain('wont_help');
    expect(texts).toContain('black_moved');
  });
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `pnpm --filter @blind-chess/server test`
Expected: the new test FAILS — `game.announcements` still contains the `wont_help` rejection from the retried attempt.

- [ ] **Step 3: Pop the intermediate rejection in `dispatch`**

In `packages/server/src/bot/driver.ts`, inside `dispatch`, replace the `if (result.kind === 'announce')` block (lines 164-176) with:

```ts
        if (result.kind === 'announce') {
          const text = result.announcements[0]!.text;
          if (text === 'wont_help' || text === 'illegal_move'
              || text === 'no_such_piece' || text === 'no_legal_moves') {
            // Feature 1: attempted-move announcements are audience 'both'.
            // The bot's intermediate retry rejections are internal search
            // churn, not deliberate probing — suppress them so they don't
            // broadcast to the human. The bot tracks its own rejections via
            // attemptHistory, so removing the announcement is safe. The whole
            // decision cycle runs before ws.ts broadcasts, so this pop always
            // happens before any broadcast.
            const rejection = result.announcements[0]!;
            const anns = this.game.announcements;
            if (anns[anns.length - 1] === rejection) anns.pop();
            return {
              kind: 'retry',
              entry: {
                move: { from: action.from, to: action.to, promotion: action.promotion },
                rejection: text,
              },
            };
          }
        }
```

- [ ] **Step 4: Run the tests to verify they pass**

Run: `pnpm --filter @blind-chess/server test`
Expected: PASS — the new test passes and all existing driver tests still pass (`retry on wont_help`, `retry cap`, `retry on illegal_move` all check retry counts / game status, not announcement contents).

- [ ] **Step 5: Commit**

```bash
git add packages/server/src/bot/driver.ts packages/server/test/unit/bot/driver.test.ts
git commit -m "feat(bot): suppress bot retry-search churn from the moderator log"
gitea push
```

---

### Task 3: Client — label attempted-move lines by player, neutral styling

The four attempted-move enums carry no colour. Derive the attempting player from `ply` parity (an attempt only happens on the actor's turn; `ply` is the pre-move history length) and drop the alarm-red styling — these lines are now shared moderator commentary.

**Files:**
- Modify: `packages/client/src/lib/ModeratorPanel.svelte`

- [ ] **Step 1: Add the actor prefix in the entry loop**

In `packages/client/src/lib/ModeratorPanel.svelte`, replace the `{#each visible ...}` block (lines 26-30) with:

```svelte
    {#each visible as a, i (i)}
      {@const isAttempt = a.text === 'no_such_piece' || a.text === 'no_legal_moves' || a.text === 'wont_help' || a.text === 'illegal_move'}
      {@const actor = a.ply % 2 === 0 ? 'White' : 'Black'}
      <div class="entry" class:attempt={isAttempt}>
        <span class="ply">{a.ply > 0 ? `#${a.ply}` : ''}</span>
        <span class="text">{isAttempt ? `${actor} — ` : ''}{moderatorText(a.text, a.payload)}</span>
      </div>
```

- [ ] **Step 2: Replace the error styling with neutral styling**

In the same file's `<style>` block, replace the rule `.entry.err .text { color: #f87171; }` with:

```css
  .entry.attempt .text { color: var(--text-dim); font-style: italic; }
```

- [ ] **Step 3: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS.

- [ ] **Step 4: Manual verification**

Start the dev servers (`pnpm dev:server` and `pnpm dev:client` in two terminals), open the client, create a **blind game vs computer**. Make a few moves; deliberately tap one of your pieces and pick a destination that is illegal. Confirm:
- The moderator panel shows your move attempts and the bot's moves.
- An illegal attempt shows e.g. `White — Illegal move.` in muted italic (not red).

- [ ] **Step 5: Commit**

```bash
git add packages/client/src/lib/ModeratorPanel.svelte
git commit -m "feat(client): label attempted-move announcements by player"
gitea push
```

---

### Task 4: Capture tally — shared type, server function, protocol field, ws wiring

The server records every capture's type in `MoveRecord`. Compute a per-viewer tally and ship it on `joined`/`update`.

**Files:**
- Modify: `packages/shared/src/types.ts` (append)
- Modify: `packages/shared/src/protocol.ts`
- Create: `packages/server/src/captures.ts`
- Modify: `packages/server/src/ws.ts`
- Test: `packages/server/test/unit/captures.test.ts`

- [ ] **Step 1: Add the `PieceTally` and `CaptureTally` types**

Append to `packages/shared/src/types.ts`:

```ts
/** Count of pieces by type — used for the capture tally. */
export type PieceTally = Partial<Record<PieceType, number>>;

/** Per-viewer capture tally: what you took, and what you lost. */
export interface CaptureTally {
  byYou: PieceTally;
  byOpponent: PieceTally;
}
```

- [ ] **Step 2: Add the `captures` field to the protocol messages**

In `packages/shared/src/protocol.ts`, add `CaptureTally` to the type import from `./types.js`, then add `captures: CaptureTally;` to **both** the `joined` and the `update` members of `ServerMessage`.

The import line becomes:

```ts
import type {
  BoardView, CaptureTally, Color, GameId, GameStatus, Mode, PlayerToken,
  PromotionType, Square, EndReason,
} from './types.js';
```

The `joined` member gains (place it after `opponentConnected: boolean;`):

```ts
      captures: CaptureTally;
```

The `update` member gains (place it after `aiOpponent?: ...;`):

```ts
      captures: CaptureTally;
```

- [ ] **Step 3: Build shared**

Run: `pnpm --filter @blind-chess/shared build`
Expected: PASS — `dist/` now exports `PieceTally` / `CaptureTally`.

- [ ] **Step 4: Write the failing test**

Create `packages/server/test/unit/captures.test.ts`:

```ts
import { describe, it, expect } from 'vitest';
import { captureTally } from '../../src/captures.js';
import type { Game, MoveRecord } from '../../src/state.js';
import type { Color, PieceType } from '@blind-chess/shared';

function rec(by: Color, capturedPieceType?: PieceType): MoveRecord {
  return {
    ply: 1, by, from: 'e2', to: 'e4', san: 'e4',
    capturedPieceType, flags: {}, at: 0,
  };
}

describe('captureTally', () => {
  it('counts captures per viewer', () => {
    const moveHistory: MoveRecord[] = [
      rec('w', 'p'), rec('b'), rec('w', 'n'),
      rec('b', 'p'), rec('w', 'p'),
    ];
    const game = { moveHistory } as unknown as Game;
    expect(captureTally(game, 'w')).toEqual({
      byYou: { p: 2, n: 1 }, byOpponent: { p: 1 },
    });
    expect(captureTally(game, 'b')).toEqual({
      byYou: { p: 1 }, byOpponent: { p: 2, n: 1 },
    });
  });

  it('returns empty tallies when there are no captures', () => {
    const game = { moveHistory: [rec('w'), rec('b')] } as unknown as Game;
    expect(captureTally(game, 'w')).toEqual({ byYou: {}, byOpponent: {} });
  });
});
```

- [ ] **Step 5: Run the test to verify it fails**

Run: `pnpm --filter @blind-chess/server test`
Expected: the new test file FAILS — `../../src/captures.js` does not exist yet.

- [ ] **Step 6: Implement `captureTally`**

Create `packages/server/src/captures.ts`:

```ts
import type { CaptureTally, Color } from '@blind-chess/shared';
import type { Game } from './state.js';

/**
 * Per-viewer capture tally derived from move history. `byYou` is the set of
 * opponent pieces this viewer has captured; `byOpponent` is the set of this
 * viewer's pieces the opponent has captured. Pure function of move history —
 * no live board state, no opponent positions.
 */
export function captureTally(game: Game, viewer: Color): CaptureTally {
  const byYou: Record<string, number> = {};
  const byOpponent: Record<string, number> = {};
  for (const rec of game.moveHistory) {
    const captured = rec.capturedPieceType;
    if (!captured) continue;
    const bucket = rec.by === viewer ? byYou : byOpponent;
    bucket[captured] = (bucket[captured] ?? 0) + 1;
  }
  return { byYou, byOpponent };
}
```

- [ ] **Step 7: Run the test to verify it passes**

Run: `pnpm --filter @blind-chess/server test`
Expected: PASS — the two new `captureTally` tests pass.

- [ ] **Step 8: Wire `captures` into the `joined` and `update` messages**

In `packages/server/src/ws.ts`:

Add the import near the other server imports (after the `import { endGame, ... }` line):

```ts
import { captureTally } from './captures.js';
```

In `onHello`, the `send(ctx.socket, { type: 'joined', ... })` call gains a field (add it after `aiOpponent: game.aiOpponent,`):

```ts
    captures: captureTally(game, color),
```

In `sendUpdateTo`, the `send(slot.socket, { type: 'update', ... })` call gains a field (add it after `aiOpponent: game.aiOpponent,`):

```ts
    captures: captureTally(game, color),
```

- [ ] **Step 9: Build and test the server**

Run: `pnpm --filter @blind-chess/server build && pnpm --filter @blind-chess/server test`
Expected: PASS — server compiles (every `joined`/`update` construction site now provides the required `captures` field) and all tests pass.

- [ ] **Step 10: Commit**

```bash
git add packages/shared/src/types.ts packages/shared/src/protocol.ts packages/server/src/captures.ts packages/server/src/ws.ts packages/server/test/unit/captures.test.ts
git commit -m "feat(server): per-viewer capture tally on joined and update messages"
gitea push
```

---

### Task 5: Client — capture-tally store field and panel

**Files:**
- Modify: `packages/client/src/lib/stores/game.svelte.ts`
- Create: `packages/client/src/lib/CaptureTally.svelte`
- Modify: `packages/client/src/lib/Game.svelte`

- [ ] **Step 1: Add `captures` to the client game store**

In `packages/client/src/lib/stores/game.svelte.ts`:

Add `CaptureTally` to the type import from `@blind-chess/shared`.

Add to the `GameStateValue` interface (after `aiOpponent: ...;`):

```ts
  captures: CaptureTally;
```

Add to the `$state<GameStateValue>({ ... })` initializer (after `aiOpponent: null,`):

```ts
    captures: { byYou: {}, byOpponent: {} },
```

In `onServerMessage`, in the `case 'joined':` block (after `state.aiOpponent = m.aiOpponent ?? null;`):

```ts
        state.captures = m.captures;
```

In the `case 'update':` block (after the `aiOpponent` line):

```ts
        state.captures = m.captures;
```

- [ ] **Step 2: Create the `CaptureTally` component**

Create `packages/client/src/lib/CaptureTally.svelte`:

```svelte
<script lang="ts">
  import type { CaptureTally, Color, PieceTally, PieceType } from '@blind-chess/shared';
  import { pieceGlyph } from './pieces.js';

  interface Props {
    captures: CaptureTally;
    you: Color;
  }
  let { captures, you }: Props = $props();

  const ORDER: PieceType[] = ['q', 'r', 'b', 'n', 'p'];
  const oppColor = $derived<Color>(you === 'w' ? 'b' : 'w');

  function glyphs(tally: PieceTally, color: Color): { glyph: string; key: string }[] {
    const out: { glyph: string; key: string }[] = [];
    for (const t of ORDER) {
      const n = tally[t] ?? 0;
      for (let i = 0; i < n; i++) out.push({ glyph: pieceGlyph({ color, type: t }), key: `${t}${i}` });
    }
    return out;
  }
  function total(tally: PieceTally): number {
    return Object.values(tally).reduce((a, b) => a + b, 0);
  }

  const youTook = $derived(glyphs(captures.byYou, oppColor));
  const youLost = $derived(glyphs(captures.byOpponent, you));
</script>

<div class="panel">
  <header>Captures</header>
  <div class="row">
    <span class="label">You took</span>
    <span class="pieces">
      {#each youTook as g (g.key)}<span class="g g-{oppColor}">{g.glyph}</span>{:else}<span class="muted">—</span>{/each}
    </span>
    <span class="n">{total(captures.byYou)}</span>
  </div>
  <div class="row lost">
    <span class="label">Lost</span>
    <span class="pieces">
      {#each youLost as g (g.key)}<span class="g g-{you}">{g.glyph}</span>{:else}<span class="muted">—</span>{/each}
    </span>
    <span class="n">{total(captures.byOpponent)}</span>
  </div>
</div>

<style>
  .panel {
    background: var(--panel);
    border: 1px solid var(--border);
    border-radius: 8px;
  }
  header {
    padding: 8px 14px;
    font-size: 13px;
    font-weight: 600;
    color: var(--text-dim);
    text-transform: uppercase;
    letter-spacing: 0.08em;
    border-bottom: 1px solid var(--border);
  }
  .row {
    display: flex;
    align-items: center;
    gap: 8px;
    padding: 8px 14px;
  }
  .row.lost { opacity: 0.7; }
  .label {
    font-size: 12px;
    color: var(--text-dim);
    width: 56px;
    flex-shrink: 0;
  }
  .pieces { flex: 1; font-size: 20px; line-height: 1; }
  .g-w { color: #fafafa; }
  .g-b { color: #1a1a1a; }
  .n {
    font-family: ui-monospace, monospace;
    font-size: 13px;
    color: var(--text-dim);
  }
</style>
```

- [ ] **Step 3: Mount the panel in `Game.svelte`**

In `packages/client/src/lib/Game.svelte`:

Add the import after the `ModeratorPanel` import:

```ts
  import CaptureTally from './CaptureTally.svelte';
```

In the `<aside class="side">` block, immediately after the `<ModeratorPanel ... />` line, add:

```svelte
      <CaptureTally captures={game.state.captures} you={game.state.you} />
```

- [ ] **Step 4: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS.

- [ ] **Step 5: Manual verification**

With dev servers running, create a **blind game vs computer**, play until you capture a bot piece (and until it captures one of yours). Confirm the Captures panel shows the right glyphs and counts in "You took" and "Lost".

- [ ] **Step 6: Commit**

```bash
git add packages/client/src/lib/stores/game.svelte.ts packages/client/src/lib/CaptureTally.svelte packages/client/src/lib/Game.svelte
git commit -m "feat(client): capture-tally panel"
gitea push
```

---

### Checkpoint A — Increment 1 complete

- [ ] **Full build, typecheck, and test:**

```bash
pnpm -r build && pnpm -r typecheck && pnpm -r test
```
Expected: all packages build; all tests pass — was 78, plus 5 new (2 in `commit-fsm`, 1 in `driver`, 2 in `captures`) = 83.

- [ ] **Deploy Increment 1.** Deploy per the `Operations` section of `CLAUDE.md` — there are now two instances (CT 690 / `chess.sethpc.xyz` and `chess.local` on VDJ-RIG). Smoke-test: `curl https://chess.sethpc.xyz/api/health`, then play a quick vs-computer blind game and confirm the moderator transcript and capture panel.

- [ ] **STOP for review before starting Increment 2.**

---

## Increment 2 — Feature 3: Phantom opponent pieces

> Client-only. The phantom layer never reaches the server — no `ClientMessage` carries phantom data, and the phantom store is never read in any `send`/`commit` path.

### Task 6: Shared pure phantom model

**Files:**
- Create: `packages/shared/src/phantoms.ts`
- Modify: `packages/shared/src/index.ts`
- Test: `packages/shared/test/phantoms.test.ts`

- [ ] **Step 1: Write the failing test**

Create `packages/shared/test/phantoms.test.ts`:

```ts
import { describe, it, expect } from 'vitest';
import { opponentStartPosition, deserializePhantoms } from '../src/phantoms.js';

describe('opponentStartPosition', () => {
  it('seeds 16 black pieces on ranks 7-8', () => {
    const p = opponentStartPosition('b');
    expect(Object.keys(p).length).toBe(16);
    expect(p.e8).toEqual({ color: 'b', type: 'k' });
    expect(p.d8).toEqual({ color: 'b', type: 'q' });
    expect(p.a8).toEqual({ color: 'b', type: 'r' });
    expect(p.h7).toEqual({ color: 'b', type: 'p' });
  });

  it('seeds 16 white pieces on ranks 1-2', () => {
    const p = opponentStartPosition('w');
    expect(Object.keys(p).length).toBe(16);
    expect(p.e1).toEqual({ color: 'w', type: 'k' });
    expect(p.a2).toEqual({ color: 'w', type: 'p' });
  });
});

describe('deserializePhantoms', () => {
  it('returns {} for null or invalid JSON', () => {
    expect(deserializePhantoms(null)).toEqual({});
    expect(deserializePhantoms('not json')).toEqual({});
    expect(deserializePhantoms('[]')).toEqual({});
  });

  it('keeps valid entries and drops invalid ones', () => {
    const raw = JSON.stringify({
      e5: { color: 'b', type: 'n' },
      zz: { color: 'b', type: 'p' },  // invalid square
      a1: { color: 'x', type: 'p' },  // invalid colour
      b2: { color: 'b', type: 'z' },  // invalid type
    });
    expect(deserializePhantoms(raw)).toEqual({ e5: { color: 'b', type: 'n' } });
  });
});
```

- [ ] **Step 2: Run the test to verify it fails**

Run: `pnpm --filter @blind-chess/shared test`
Expected: FAIL — `../src/phantoms.js` does not exist.

- [ ] **Step 3: Implement the phantom model**

Create `packages/shared/src/phantoms.ts`:

```ts
import { FILES, isSquare, type Color, type Piece, type PieceType, type Square } from './types.js';

const BACK_RANK: PieceType[] = ['r', 'n', 'b', 'q', 'k', 'b', 'n', 'r'];
const COLORS: Color[] = ['w', 'b'];
const TYPES: PieceType[] = ['p', 'n', 'b', 'r', 'q', 'k'];

/**
 * The standard starting position for one colour, as a square→piece map.
 * Used to seed the phantom opponent-model layer with the opponent's army.
 */
export function opponentStartPosition(opponentColor: Color): Partial<Record<Square, Piece>> {
  const backRank = opponentColor === 'w' ? '1' : '8';
  const pawnRank = opponentColor === 'w' ? '2' : '7';
  const out: Partial<Record<Square, Piece>> = {};
  FILES.forEach((file, i) => {
    out[`${file}${backRank}` as Square] = { color: opponentColor, type: BACK_RANK[i]! };
    out[`${file}${pawnRank}` as Square] = { color: opponentColor, type: 'p' };
  });
  return out;
}

/**
 * Parse a persisted phantom map (from localStorage). Tolerant: returns {} on
 * any structural failure and silently drops individual invalid entries.
 */
export function deserializePhantoms(raw: string | null): Partial<Record<Square, Piece>> {
  if (!raw) return {};
  let parsed: unknown;
  try { parsed = JSON.parse(raw); } catch { return {}; }
  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return {};
  const out: Partial<Record<Square, Piece>> = {};
  for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
    if (!isSquare(k)) continue;
    if (typeof v !== 'object' || v === null) continue;
    const { color, type } = v as { color?: unknown; type?: unknown };
    if (!COLORS.includes(color as Color)) continue;
    if (!TYPES.includes(type as PieceType)) continue;
    out[k] = { color: color as Color, type: type as PieceType };
  }
  return out;
}
```

- [ ] **Step 4: Export from the shared index**

In `packages/shared/src/index.ts`, append:

```ts
export * from './phantoms.js';
```

- [ ] **Step 5: Run the test and build**

Run: `pnpm --filter @blind-chess/shared test && pnpm --filter @blind-chess/shared build`
Expected: PASS — the new tests pass and `dist/` exports the phantom model.

- [ ] **Step 6: Commit**

```bash
git add packages/shared/src/phantoms.ts packages/shared/src/index.ts packages/shared/test/phantoms.test.ts
git commit -m "feat(shared): pure phantom-model helpers (seed positions, deserialize)"
gitea push
```

---

### Task 7: Client phantom store

A local-only Svelte store, persisted to `localStorage`, seeded once per game.

**Files:**
- Create: `packages/client/src/lib/stores/phantoms.svelte.ts`

- [ ] **Step 1: Create the store**

Create `packages/client/src/lib/stores/phantoms.svelte.ts`:

```ts
import {
  opponentStartPosition,
  deserializePhantoms,
  type Color,
  type Piece,
  type PieceType,
  type Square,
} from '@blind-chess/shared';

/**
 * Client-LOCAL store for the player's phantom opponent-model layer.
 * This data NEVER reaches the server — it is the player's private guess.
 * Do not read this store in any `send`/`commit` path.
 */
function makeStore() {
  const state = $state<{ phantoms: Partial<Record<Square, Piece>> }>({ phantoms: {} });
  let gameId: string | null = null;
  let oppColor: Color = 'b';

  function key(id: string) { return `bc:phantoms:${id}`; }

  function persist() {
    if (gameId) localStorage.setItem(key(gameId), JSON.stringify(state.phantoms));
  }

  /** Load (or first-time seed) the phantom layer for a blind game. */
  function loadForGame(id: string, you: Color) {
    gameId = id;
    oppColor = you === 'w' ? 'b' : 'w';
    const raw = localStorage.getItem(key(id));
    if (raw === null) {
      // First load — seed with the opponent's starting army.
      state.phantoms = opponentStartPosition(oppColor);
      persist();
    } else {
      state.phantoms = deserializePhantoms(raw);
    }
  }

  function place(sq: Square, type: PieceType) {
    state.phantoms = { ...state.phantoms, [sq]: { color: oppColor, type } };
    persist();
  }

  function move(from: Square, to: Square) {
    const p = state.phantoms[from];
    if (!p) return;
    const next = { ...state.phantoms };
    delete next[from];
    next[to] = p;
    state.phantoms = next;
    persist();
  }

  function remove(sq: Square) {
    const next = { ...state.phantoms };
    delete next[sq];
    state.phantoms = next;
    persist();
  }

  /** Drop the layer when a game ends — avoids unbounded localStorage growth. */
  function clearForGame(id: string) {
    localStorage.removeItem(key(id));
    if (gameId === id) { state.phantoms = {}; gameId = null; }
  }

  return { state, loadForGame, place, move, remove, clearForGame };
}

export const phantoms = makeStore();
```

- [ ] **Step 2: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS.

- [ ] **Step 3: Commit**

```bash
git add packages/client/src/lib/stores/phantoms.svelte.ts
git commit -m "feat(client): local-only phantom-layer store"
gitea push
```

---

### Task 8: Client drag controller

Pointer-event drag shared by the board (phantom move/remove) and the palette (phantom place). Distinguishes a tap from a drag so a tap on a phantom still passes through to a real move.

**Files:**
- Create: `packages/client/src/lib/stores/phantom-drag.svelte.ts`

- [ ] **Step 1: Create the drag controller**

Create `packages/client/src/lib/stores/phantom-drag.svelte.ts`:

```ts
import type { PieceType, Square } from '@blind-chess/shared';
import { phantoms } from './phantoms.svelte.js';
import { game } from './game.svelte.js';

export type DragSource =
  | { kind: 'palette'; type: PieceType }
  | { kind: 'board'; from: Square; type: PieceType };

/**
 * Pointer-event drag controller for the phantom layer. A drag past THRESHOLD
 * px places/moves/removes a phantom; a sub-threshold press is a tap and is
 * left for the board's normal click handler. Real moves are unaffected.
 */
function makeDrag() {
  const state = $state<{
    active: DragSource | null;
    x: number;
    y: number;
    moved: boolean;
  }>({ active: null, x: 0, y: 0, moved: false });

  let startX = 0;
  let startY = 0;
  // Set only when a board-phantom drag ends back on its origin square — the
  // browser then fires a spurious `click` on that square's button which must
  // be swallowed so it doesn't trigger a real move.
  let suppressClickOn: Square | null = null;
  const THRESHOLD = 6;

  function onMove(e: PointerEvent) {
    if (!state.active) return;
    state.x = e.clientX;
    state.y = e.clientY;
    if (!state.moved && Math.hypot(e.clientX - startX, e.clientY - startY) > THRESHOLD) {
      state.moved = true;
    }
  }

  function onUp(e: PointerEvent) {
    window.removeEventListener('pointermove', onMove);
    window.removeEventListener('pointerup', onUp);
    const src = state.active;
    const wasDrag = state.moved;
    state.active = null;
    state.moved = false;
    if (!src || !wasDrag) return; // a tap — the board click handler deals with it

    const el = document.elementFromPoint(e.clientX, e.clientY);
    const sqEl = el?.closest('[data-square]') as HTMLElement | null;
    const target = sqEl?.dataset.square as Square | undefined;

    if (src.kind === 'board') {
      if (target === src.from) { suppressClickOn = src.from; return; }
      if (!target) { phantoms.remove(src.from); return; } // dropped off the board
      if (game.state.view?.pieces[target]) return;        // your own real piece — reject
      phantoms.move(src.from, target);
      return;
    }
    // palette → board
    if (target && !game.state.view?.pieces[target]) phantoms.place(target, src.type);
  }

  function start(src: DragSource, e: PointerEvent) {
    suppressClickOn = null;
    state.active = src;
    state.x = startX = e.clientX;
    state.y = startY = e.clientY;
    state.moved = false;
    window.addEventListener('pointermove', onMove);
    window.addEventListener('pointerup', onUp);
  }

  /** The board calls this first in its square-click handler. */
  function shouldSuppressClick(sq: Square): boolean {
    if (suppressClickOn === sq) { suppressClickOn = null; return true; }
    return false;
  }

  return { state, start, shouldSuppressClick };
}

export const phantomDrag = makeDrag();
```

- [ ] **Step 2: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS.

- [ ] **Step 3: Commit**

```bash
git add packages/client/src/lib/stores/phantom-drag.svelte.ts
git commit -m "feat(client): pointer-event drag controller for the phantom layer"
gitea push
```

---

### Task 9: Render phantoms and drag handles in `Board.svelte`

**Files:**
- Modify: `packages/client/src/lib/Board.svelte`

- [ ] **Step 1: Import the drag controller**

In the `<script>` block of `packages/client/src/lib/Board.svelte`, after the `import { pieceGlyph }` line, add:

```ts
  import { phantomDrag } from './stores/phantom-drag.svelte.js';
```

- [ ] **Step 2: Add the new props (optional, with defaults)**

In the `Props` interface, after `highlightingEnabled: boolean;`, add two **optional** props (optional so `Board.svelte` typechecks on its own before `Game.svelte` is updated in Task 11):

```ts
    phantoms?: Partial<Record<Square, Piece>>;
    phantomsEnabled?: boolean;
```

In the `let { ... }: Props = $props();` destructuring, add them with defaults (e.g. after `highlightingEnabled,`):

```ts
    phantoms = {}, phantomsEnabled = false,
```

- [ ] **Step 3: Add the dragged-origin derived value**

After the `highlights` `$derived.by(...)` block, add:

```ts
  // The board square a phantom is currently being dragged out of (so it can
  // be dimmed while the drag ghost is shown). Bind `active` to a local first
  // so TypeScript narrows the discriminated union reliably.
  const dragOrigin = $derived.by(() => {
    const a = phantomDrag.state.active;
    return a?.kind === 'board' && phantomDrag.state.moved ? a.from : null;
  });
```

- [ ] **Step 4: Suppress the post-drag click in `onSquareClick`**

Make the first line of the `onSquareClick` function body:

```ts
  function onSquareClick(sq: Square) {
    if (phantomDrag.shouldSuppressClick(sq)) return;
    const piece = pieces[sq];
```

- [ ] **Step 5: Render the phantom layer**

In the markup, the square loop currently has these `{@const}` lines:

```svelte
      {@const sq = `${f}${r}` as Square}
      {@const piece = pieces[sq]}
```

Add a third after them:

```svelte
      {@const ph = phantomsEnabled ? phantoms[sq] : undefined}
```

On the `<button>` element add a `data-square` attribute (next to `aria-label={sq}`):

```svelte
        data-square={sq}
```

Inside the button, immediately after the `{#if piece}...{/if}` block and before the `{#if isHighlight && !piece}` block, add:

```svelte
        {#if ph && !piece}
          <span
            class="phantom phantom-{ph.color}"
            class:dragging={sq === dragOrigin}
            onpointerdown={(e) => { e.preventDefault(); phantomDrag.start({ kind: 'board', from: sq, type: ph.type }, e); }}
          >{pieceGlyph(ph)}</span>
        {/if}
```

- [ ] **Step 6: Add phantom styles**

In the `<style>` block, after the `.piece-b { ... }` rule, add:

```css
  .phantom {
    position: absolute;
    inset: 0;
    display: flex;
    align-items: center;
    justify-content: center;
    pointer-events: auto;
    touch-action: none;
    cursor: grab;
    opacity: 0.4;
    outline: 2px dashed var(--text-dim);
    outline-offset: -5px;
  }
  .phantom-w { color: #fafafa; }
  .phantom-b { color: #1a1a1a; }
  .phantom.dragging { opacity: 0.12; }
```

(The translucency plus the dashed inset frame make a phantom unmistakable from a real piece — tune to taste during manual verification.)

- [ ] **Step 7: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS — the new props are optional with defaults, so `Board.svelte` typechecks even though `Game.svelte` does not pass them yet (Task 11 wires them).

- [ ] **Step 8: Commit**

```bash
git add packages/client/src/lib/Board.svelte
git commit -m "feat(client): render and drag phantom pieces on the board"
gitea push
```

---

### Task 10: `PhantomPalette` component

A row of the six opponent piece types; drag one onto the board to place a phantom.

**Files:**
- Create: `packages/client/src/lib/PhantomPalette.svelte`

- [ ] **Step 1: Create the component**

Create `packages/client/src/lib/PhantomPalette.svelte`:

```svelte
<script lang="ts">
  import type { Color, PieceType } from '@blind-chess/shared';
  import { pieceGlyph } from './pieces.js';
  import { phantomDrag } from './stores/phantom-drag.svelte.js';

  interface Props { oppColor: Color; }
  let { oppColor }: Props = $props();

  const TYPES: PieceType[] = ['q', 'r', 'b', 'n', 'p', 'k'];
</script>

<div class="palette">
  <span class="hint muted">Drag onto your board — your guess of where the opponent is.</span>
  <div class="pieces">
    {#each TYPES as t (t)}
      <span
        class="pp pp-{oppColor}"
        role="button"
        tabindex="0"
        aria-label={`place ${t}`}
        onpointerdown={(e) => { e.preventDefault(); phantomDrag.start({ kind: 'palette', type: t }, e); }}
      >{pieceGlyph({ color: oppColor, type: t })}</span>
    {/each}
  </div>
</div>

<style>
  .palette {
    display: flex;
    flex-direction: column;
    gap: 4px;
    background: var(--panel);
    border: 1px solid var(--border);
    border-radius: 8px;
    padding: 8px 12px;
  }
  .hint { font-size: 12px; }
  .pieces { display: flex; gap: 6px; }
  .pp {
    font-size: 30px;
    line-height: 1;
    cursor: grab;
    touch-action: none;
    opacity: 0.75;
    user-select: none;
  }
  .pp:hover { opacity: 1; }
  .pp-w { color: #fafafa; }
  .pp-b { color: #1a1a1a; }
</style>
```

- [ ] **Step 2: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS — `PhantomPalette.svelte` is self-contained.

- [ ] **Step 3: Commit**

```bash
git add packages/client/src/lib/PhantomPalette.svelte
git commit -m "feat(client): phantom-piece palette component"
gitea push
```

---

### Task 11: Wire the phantom layer into `Game.svelte`

Load/clear the phantom store, pass phantoms to the board, mount the palette, and render the drag ghost.

**Files:**
- Modify: `packages/client/src/lib/Game.svelte`

- [ ] **Step 1: Add imports**

In the `<script>` block of `packages/client/src/lib/Game.svelte`, after the existing component imports, add:

```ts
  import PhantomPalette from './PhantomPalette.svelte';
  import { pieceGlyph } from './pieces.js';
  import { phantoms } from './stores/phantoms.svelte.js';
  import { phantomDrag } from './stores/phantom-drag.svelte.js';
```

- [ ] **Step 2: Add derived gating values**

After the existing `const turnLabel = ...` derived block, add:

```ts
  const oppColor = $derived<'w' | 'b'>(game.state.you === 'w' ? 'b' : 'w');

  // Phantom layer is blind-mode-only and shown only during active play.
  const phantomLayerEnabled = $derived(
    game.state.mode === 'blind' && game.state.gameStatus === 'active',
  );

  // The piece type currently being dragged (for the floating ghost), or null.
  const dragGhost = $derived.by(() => {
    const a = phantomDrag.state.active;
    return a && phantomDrag.state.moved ? a.type : null;
  });

  // Load the phantom layer once `you` is known (blind games only).
  let phantomsLoaded = $state(false);
  $effect(() => {
    if (phantomsLoaded) return;
    const you = game.state.you;
    if (you && game.state.mode === 'blind') {
      untrack(() => phantoms.loadForGame(gameId, you));
      phantomsLoaded = true;
    }
  });

  // Drop the phantom layer when the game ends.
  $effect(() => {
    if (game.state.gameStatus === 'finished') {
      untrack(() => phantoms.clearForGame(gameId));
    }
  });
```

(`untrack` is already imported at the top of `Game.svelte`.)

- [ ] **Step 3: Pass phantoms to `Board` and mount the palette**

Replace the `<div class="board-area">...</div>` block with:

```svelte
    <div class="board-area">
      <Board
        pieces={game.state.view.pieces}
        you={game.state.you}
        toMove={game.state.view.toMove}
        mode={game.state.mode ?? 'blind'}
        highlightingEnabled={game.state.highlightingEnabled}
        phantoms={phantomLayerEnabled ? phantoms.state.phantoms : {}}
        phantomsEnabled={phantomLayerEnabled}
        armedSquare={armedSquare}
        touchedSquare={game.state.touchedPiece}
        {onArm}
        {onCommit}
      />
      {#if phantomLayerEnabled}
        <PhantomPalette {oppColor} />
      {/if}
    </div>
```

- [ ] **Step 4: Render the drag ghost**

Immediately after the closing `</div>` of `<div class="game-layout" ...>` (and before the `{#if pendingPromotion ...}` block), add:

```svelte
{#if dragGhost}
  <div
    class="drag-ghost piece-{oppColor}"
    style="left: {phantomDrag.state.x}px; top: {phantomDrag.state.y}px;"
  >{pieceGlyph({ color: oppColor, type: dragGhost })}</div>
{/if}
```

- [ ] **Step 5: Add layout styles for the palette and ghost**

In the `<style>` block, replace the `.board-area { ... }` rule with:

```css
  .board-area {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    gap: 10px;
  }
```

Then append:

```css
  .drag-ghost {
    position: fixed;
    transform: translate(-50%, -50%);
    pointer-events: none;
    z-index: 1000;
    font-size: 44px;
    line-height: 1;
    text-shadow: 0 2px 6px rgba(0, 0, 0, 0.6);
  }
  .drag-ghost.piece-w { color: #fafafa; }
  .drag-ghost.piece-b { color: #1a1a1a; }
```

- [ ] **Step 6: Typecheck**

Run: `pnpm --filter @blind-chess/client typecheck`
Expected: PASS — the `Board.svelte` props are now satisfied.

- [ ] **Step 7: Manual verification**

With dev servers running, create a **blind game vs computer**. Confirm:
- The board shows 16 translucent phantom pieces on the opponent's home ranks.
- A palette of six piece types appears below the board.
- Dragging a phantom to another square moves it; dragging it off the board removes it.
- Dragging a palette piece onto a board square places a phantom there.
- A phantom cannot be dropped onto a square holding one of your own real pieces (the drop is rejected).
- Tapping (not dragging) a square still arms/commits real moves normally, including onto a square that has a phantom.
- Reload the page mid-game — phantoms persist (loaded from `localStorage`, not re-seeded).
- Create a **vanilla** vs-computer game — no phantom layer or palette appears.
- When a game ends, the phantom layer and palette disappear and the full board is revealed cleanly.

- [ ] **Step 8: Commit**

```bash
git add packages/client/src/lib/Game.svelte
git commit -m "feat(client): wire the phantom opponent-model layer into the game view"
gitea push
```

---

### Checkpoint B — Increment 2 complete

- [ ] **Full build, typecheck, and test:**

```bash
pnpm -r build && pnpm -r typecheck && pnpm -r test
```
Expected: all packages build; all tests pass (Increment 1's 83 + 4 new phantom-model tests = 87).

- [ ] **Deploy Increment 2** per the `Operations` section of `CLAUDE.md` (both instances: CT 690 / `chess.sethpc.xyz` and `chess.local` on VDJ-RIG). Smoke-test the phantom layer on a phone and on desktop in a vs-computer blind game.

- [ ] **Update `DECISIONS.md`** with the locked choices from this work: announcement audience widened to `'both'`; manual phantom model (seeded once, no automation); drag-and-drop interaction for phantoms only (real moves stay click-to-move); phantom layer is client-local and never serialized to the server.

- [ ] **Write a session handoff** via the `/session-handoff` skill.

---

## Notes on testing scope

`packages/shared` and `packages/server` have `vitest`; `packages/client` does not, by deliberate decision (the spec left this to the plan). Feature 3's genuinely-testable logic — start positions and deserialization — lives in `packages/shared/src/phantoms.ts` and is unit-tested there. The client store, drag controller, and Svelte components are covered by `svelte-check` typechecking plus the manual-verification steps. Standing up a client test harness is out of scope for this plan.