+ checkmate.blue
+
+ checkmate.blue
+
+```
+
+### Acceptance Criteria
+
+- [ ] `static/logo.svg` exists with the knight icon in `#0085FF`.
+- [ ] `static/favicon.svg` replaced with the knight icon.
+- [ ] `static/og-default.png` exists at 1200x630 with logo + text on dark background.
+- [ ] Navbar shows the logo icon alongside the site name.
+- [ ] Favicon displays correctly in browser tabs.
+
+### Edge Cases
+
+- SVG favicon support: all modern browsers support SVG favicons. No PNG fallback needed for the PoC, but the Apple touch icon covers iOS.
+
+---
+
+## 2b. Open Graph Meta Tags
+
+### Overview
+
+Add meta tags so shared links show rich previews. Start with static/generic tags (same card for all routes), with a plan for dynamic per-route tags via a Cloudflare Worker later.
+
+### Implementation
+
+#### Step 1: Static Meta Tags (Immediate)
+
+**Update `src/app.html`:**
+
+Add OG and Twitter Card meta tags to the ``:
+
+```html
+
+
+
+
+
+
+
+
+
+
+```
+
+This gives every page the same generic card. Not ideal but functional.
+
+#### Step 2: Dynamic OG Tags via Cloudflare Worker (Fast Follow)
+
+**Separate deployment** -- a Cloudflare Worker sits in front of the static site and intercepts requests from known bot user agents.
+
+**Bot user agents to detect:**
+
+```
+Twitterbot, facebookexternalhit, LinkedInBot, Slackbot, Discordbot,
+WhatsApp, TelegramBot, Bluesky (cardyb)
+```
+
+**Worker logic:**
+
+1. Check `User-Agent` header against bot list.
+2. If not a bot, pass through to the static site (origin).
+3. If a bot, parse the URL path:
+ - `/game/{did}/{rkey}` -- fetch game record from PDS, extract player handles/status/move count, return HTML with dynamic OG tags.
+ - `/challenge/{did}/{rkey}` -- fetch challenge record, return HTML with challenger info.
+ - `/profile/{handle}` -- resolve handle, return HTML with profile info.
+ - All other routes -- return generic OG tags.
+4. Return a minimal HTML document with just the `` containing OG tags. The body can be empty or contain a redirect meta tag -- bots only read the head.
+
+**Dynamic OG content per route:**
+
+| Route | og:title | og:description | og:image |
+|-------|----------|---------------|----------|
+| `/` | checkmate.blue | Chess on the Atmosphere | `/og-default.png` |
+| `/game/{did}/{rkey}` | {whiteHandle} vs {blackHandle} | {status} -- {moveCount} moves played | `/og-default.png` (or dynamic board image later) |
+| `/challenge/{did}/{rkey}` | Chess Challenge from {handle} | {handle} wants to play chess on checkmate.blue | `/og-default.png` |
+| `/profile/{handle}` | {handle} on checkmate.blue | Chess profile on checkmate.blue | `/og-default.png` |
+
+**Worker needs to:**
+- Resolve DIDs to handles via Slingshot or public API.
+- Fetch game records via public `getRecord` (no auth needed).
+- Cache responses (OG tags don't need to be real-time; 5-minute TTL is fine).
+
+**This is a separate deployment artifact** but can live in this repo under a `worker/` directory, or in its own repo. Decision left to implementation time.
+
+#### Step 3: Dynamic OG Images (Nice-to-Have)
+
+Generate per-game OG images showing the board position. This would be a separate service (Cloudflare Worker with `@cloudflare/pages-plugin-satori` or similar) that:
+
+1. Receives a request like `/og/game/{did}/{rkey}.png`.
+2. Fetches the game record, extracts the FEN from the PGN.
+3. Renders a chess board as an SVG/PNG with player names, move count, and status.
+4. Returns the image with cache headers.
+
+The Cloudflare Worker from Step 2 would reference this URL in the `og:image` tag for game routes.
+
+**Deferred** -- the static `og-default.png` is sufficient for launch.
+
+### Acceptance Criteria
+
+#### Step 1 (Static)
+- [ ] `app.html` contains OG and Twitter Card meta tags.
+- [ ] Sharing any checkmate.blue URL on Bluesky/Twitter/Discord shows a card with the logo image, title, and description.
+
+#### Step 2 (Dynamic Worker)
+- [ ] Sharing a game URL shows the player handles and game status in the card.
+- [ ] Sharing a challenge URL shows the challenger's handle.
+- [ ] Non-bot requests pass through to the SPA with no change in behavior.
+- [ ] Worker responses are cached (5-minute TTL).
+
+### Edge Cases
+
+- Bot user agent detection is imperfect. Some bots may not be caught (they get generic tags -- acceptable). Some real users may be misidentified as bots (they get the minimal HTML -- the meta refresh or JS redirect handles this).
+- Game records may not exist (deleted, invalid rkey) -- worker falls back to generic tags.
+- Handle resolution may fail -- use the DID as fallback text.
+
+---
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `static/logo.svg` | Knight logo in AT Protocol blue |
+| `static/og-default.png` | Default OG card image (1200x630) |
+| `static/icon-192.png` | PWA icon |
+| `static/icon-512.png` | PWA icon |
+| `static/apple-touch-icon.png` | iOS home screen icon |
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `src/app.html` | Add OG and Twitter Card meta tags |
+| `src/routes/+layout.svelte` | Update favicon ref, add apple-touch-icon, add logo to navbar |
+| `static/favicon.svg` | Replace with knight logo |
diff --git a/plans/phase-3-spectator-mode.md b/plans/phase-3-spectator-mode.md
new file mode 100644
index 0000000..1af1859
--- /dev/null
+++ b/plans/phase-3-spectator-mode.md
@@ -0,0 +1,61 @@
+# Phase 3: Spectator Mode
+
+Status: **Implemented** (branch: `phase-1-challenge-invite-flow`)
+
+Pulled forward and implemented alongside Phase 1 because spectator mode is the natural fallback when multiple people click a shared game link.
+
+---
+
+## What Was Implemented
+
+### Read-Only Game View -- DONE
+
+Non-participants (logged in or not) see a fully functional spectator view:
+
+- Board rendered in view-only mode (`movable: false`, no legal move indicators)
+- "Spectating" label displayed
+- "Flip board" button toggles between White/Black perspective
+- GameControls (resign, draw offer) hidden
+- Player bars show handles with correct active-turn indicators based on board orientation
+- Game result displayed for completed games
+
+### Unauthenticated Viewing -- DONE
+
+Non-logged-in users can view any game. The `$effect` that triggers `loadGame()` now fires after auth initialization completes regardless of login status. Record reads use public (unauthenticated) agents.
+
+**New helpers in `atproto.ts`:**
+- `getGamePublic(did, rkey)` -- reads a game record without authentication
+- `findGameRecordByParentPublic(did, parentUri)` -- finds child records without authentication
+
+### Dual Jetstream Connections -- DONE
+
+Spectators subscribe to both players' DIDs via two separate `JetstreamConnection` instances. The `jsConnections` array (replacing the single `jsConnection`) tracks all connections and cleans them up on navigation.
+
+Connection status indicator shows "Live" when at least one connection is active.
+
+### Game-Full Fallback -- DONE
+
+When a non-participant loads a game where both slots are filled, they're placed in spectator mode instead of seeing an error. This handles:
+- Multiple people clicking a publicly shared link
+- Someone visiting a game they're not part of
+- Direct link sharing for spectating
+
+### Check-Before-Join -- DONE
+
+Before creating a child record to join, the game page re-fetches the owner's record to verify the slot is still open. If filled between the first fetch and the re-fetch, the viewer enters spectator mode. This reduces (but doesn't eliminate) orphaned records from race conditions.
+
+---
+
+## What Was NOT Implemented
+
+- **Spectator count** -- would need a server component. Out of scope.
+- **Partial connection indicator** -- the spec proposed a yellow "warning" state when one of two Jetstream connections drops. The implementation uses a simpler binary (connected if any connection is live).
+
+---
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `src/routes/game/[did]/[rkey]/+page.svelte` | `isSpectator` state, unauthenticated loading, `reconcileSpectator()`, `connectJetstreamSpectator()`, `destroyConnections()`, flip board, spectator UI |
+| `src/lib/atproto.ts` | `getGamePublic()`, `findGameRecordByParentPublic()` |
diff --git a/plans/phase-4-homepage-game-discovery.md b/plans/phase-4-homepage-game-discovery.md
new file mode 100644
index 0000000..f558198
--- /dev/null
+++ b/plans/phase-4-homepage-game-discovery.md
@@ -0,0 +1,291 @@
+# Phase 4: Homepage & Game Discovery
+
+Priority: **Medium**
+
+## Problem
+
+The homepage only shows the logged-in user's own games as a list of opaque rkey links. There's no way to see what's happening on the platform, no way to discover active games to watch, and the game list provides no useful information at a glance. New visitors see nothing but a login prompt.
+
+## Current State
+
+**Homepage (`src/routes/+page.svelte`):**
+
+- Logged in: shows "Your Games" fetched via `findGamesForPlayer(did)` from Constellation. Each game is displayed as a clickable rkey string (line 71) -- no player names, no status, no move count.
+- Not logged in: shows title + login form. No content for unauthenticated visitors.
+
+**Constellation query (`src/lib/microcosm.ts`):**
+
+`findGamesForPlayer(did)` queries `constellation.microcosm.blue/links/all?target={did}&collection=blue.checkmate.game`. This returns all game records across the network that reference the given DID (games where they appear as white or black). Returns `{ uri, collection, path, target }` -- just record URIs, no record content.
+
+**Deduplication problem:** Each game has two records (White's and Black's). Constellation returns both for any player. The homepage currently shows all of them, leading to duplicates.
+
+**Key files:**
+- `src/routes/+page.svelte` -- homepage
+- `src/lib/microcosm.ts` -- Constellation/Slingshot helpers
+- `src/lib/atproto.ts` -- record CRUD
+- `src/lib/types.ts` -- record types
+
+---
+
+## Lexicon Change: `lastMoveAt`
+
+Add a `lastMoveAt` field to the `blue.checkmate.game` lexicon. This is needed for sorting games by recent activity without parsing PGN.
+
+**In `lexicons/blue.checkmate.game.json`**, add to `properties`:
+
+```json
+"lastMoveAt": {
+ "type": "string",
+ "format": "datetime",
+ "description": "Timestamp of the most recent move"
+}
+```
+
+**In `src/lib/types.ts`**, add to `GameRecord`:
+
+```typescript
+lastMoveAt?: string;
+```
+
+**Update `writeMove` in the game page** to include `lastMoveAt`:
+
+```typescript
+await updateGame(auth.agent, myRkey, {
+ pgn,
+ lastMoveAt: new Date().toISOString(),
+ status: game.result ? 'completed' : 'active',
+ // ... existing fields
+});
+```
+
+This is backward-compatible -- existing records without `lastMoveAt` still work; they just sort to the bottom or use `createdAt` as fallback.
+
+---
+
+## 4a. User's Active Games (Improved)
+
+### Overview
+
+Replace the current bare rkey list with rich game cards showing player handles, game status, move count, and whose turn it is.
+
+### Implementation
+
+**Fetch game records, not just URIs:**
+
+The current flow gets URIs from Constellation, then renders them directly. To show rich info, we need to fetch the actual game records.
+
+```typescript
+async function loadGames(did: string) {
+ const links = await findGamesForPlayer(did);
+
+ // Deduplicate: only keep records where we are the owner (our DID in the URI)
+ // OR where there is no parentGameUri (White's canonical record).
+ // Since we can't filter without reading, fetch all and filter.
+ const gamePromises = links.map(async (link) => {
+ const parsed = parseAtUri(link.uri);
+ if (!parsed) return null;
+ const record = await getGamePublic(parsed.did, parsed.rkey);
+ if (!record) return null;
+ return { ...parsed, record };
+ });
+
+ const results = await Promise.all(gamePromises);
+
+ // Deduplicate: if we have both White's and Black's record for the same game,
+ // keep only the one WITHOUT parentGameUri (White's canonical record).
+ const canonical = results.filter((g) => g && !g.record.parentGameUri);
+
+ // Sort: active games first, then by lastMoveAt (or createdAt fallback), descending.
+ games = canonical
+ .sort((a, b) => {
+ const aTime = a.record.lastMoveAt || a.record.createdAt;
+ const bTime = b.record.lastMoveAt || b.record.createdAt;
+ return bTime.localeCompare(aTime);
+ });
+}
+```
+
+**Performance concern:** Fetching N game records individually is slow. Mitigation:
+- Constellation typically returns a bounded number of results.
+- Use `Promise.all` for parallel fetches.
+- Consider adding Slingshot caching for records if available.
+- Limit to most recent 20 games initially.
+
+**Game card component: `src/lib/components/GameCard.svelte`**
+
+Displays a single game in the list:
+
+```
+┌──────────────────────────────────────┐
+│ whiteHandle vs blackHandle │
+│ Active -- 24 moves -- White to move │
+│ Last activity: 5 minutes ago │
+└──────────────────────────────────────┘
+```
+
+Props:
+- `game: { did: string, rkey: string, record: GameRecord }`
+
+The component resolves handles from DIDs using `resolveIdentity`. To avoid N+1 handle resolution, batch-resolve or cache results.
+
+**Handle caching:**
+
+Create a simple in-memory handle cache in `microcosm.ts`:
+
+```typescript
+const handleCache = new MapLoading games...
+ {:else} + {#if activeGames.length > 0} +Shared!
+ {/if} +{/if} +``` + +**State variables:** + +```typescript +let shareText = $state(''); +let sharing = $state(false); +let shared = $state(false); +let dismissShare = $state(false); +``` + +**Initialize `shareText`** when the game result is detected: + +```typescript +$effect(() => { + if (game.result && !shareText) { + shareText = composeGameResultPost( + game.myColor, + game.result, + opponentHandle ?? 'opponent', + game.moveCount, + ); + } +}); +``` + +### Post Creation + +```typescript +async function shareResult() { + if (!auth.agent || !shareText.trim()) return; + sharing = true; + + const opponentDid = game.myColor === 'white' ? game.blackDid : game.whiteDid; + const gameUrl = `https://checkmate.blue/game/${ownerDid}/${rkey}`; + + // Build known handles map for facet detection + const handles = new Map