From be8ecd96b658a4bcd157c0f13ec1cb3c19e1f139 Mon Sep 17 00:00:00 2001
From: "claude (blind_chess)" <claude@sethpc.xyz>
Date: Mon, 18 May 2026 19:17:23 -0400
Subject: [PATCH] docs: implementation plan for table-fidelity feature batch

12-task TDD plan in two increments:
- Increment 1 (Tasks 1-5): announce-all-to-both + capture tally.
- Increment 2 (Tasks 6-11): client-local phantom opponent-piece layer.

Each task has exact files, complete code, and verification commands.
Server/shared tasks are TDD'd with vitest; client tasks use svelte-check
plus manual verification (no client test harness, by design).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-18-table-fidelity-features.md     | 1322 +++++++++++++++++
 1 file changed, 1322 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-18-table-fidelity-features.md

diff --git a/docs/superpowers/plans/2026-05-18-table-fidelity-features.md b/docs/superpowers/plans/2026-05-18-table-fidelity-features.md
new file mode 100644
index 0000000..343a8c3
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-18-table-fidelity-features.md
@@ -0,0 +1,1322 @@
+# 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.