Wave 2A: real player headshots — sport-agnostic id threaded from ingestion

Threads a REAL athlete id from the snapshot's per-player stats resolve (zero
new I/O) → enriched grade → grades:{sport} → slate strip → PlayerAvatar. Real
photo where an id resolves; team-colored monogram (never a gray silhouette,
never a broken image) where it can't. Ids are never fabricated.

Ingestion (Addition 1):
- espnStatsAdapter.getSeasonAverages now RETURNS the resolved ESPN athlete id
  (was discarded) as espnId; non-numeric uid degrades to null.
- playerIntelService surfaces MLBAM playerId (MLB) / ESPN espnId (NBA/WNBA).
- snapshotService captures both per player and stores them on the enriched
  grade beside archetype/team (null when unresolved → monogram path).

Thread → component:
- slateAdapter.buildPlayerStripsFromProps carries playerId/espnId onto each
  strip; StatStrip → PlayerAvatar (accepts both ids; getHeadshotUrl routes by
  sport: MLB→mlbstatic, NBA/WNBA→a.espncdn).
- Silhouette surfaces rewired to PlayerAvatar (branded monogram on null):
  scan search dropdown (guarded MLBAM p.id) + tonight chips, SearchModal,
  HotListPanel, GradeResultCard header. Scan grade card feeds the picked
  MLBAM id through gradeAdapter.
- playerHeadshot pure URL logic extracted to CommonJS playerHeadshotUrl.js
  (unit-testable; the .ts re-exports it). nfl/nhl added to ESPN_SPORT_PATH.

Tests: tests/unit/headshotThread.test.js (per-league URL + id thread + monogram
null path) + extended snapshotService/espnStatsAdapter suites. Full suite
241 suites / 2915 green; next build exit 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/unit/espnStatsAdapter.test.js

@@ -40,6 +40,20 @@ describe('getSeasonAverages (injected http)', () => {
     expect(r.found).toBe(true);
     expect(r.team).toBe('DAL');
     expect(r.classifierInput.ppg).toBe(33);
+    // Wave 2A — the REAL ESPN athlete id is surfaced (headshot CDN), not discarded.
+    expect(r.espnId).toBe('123');
+  });
+
+  it('Wave 2A — a non-numeric uid degrades espnId to null (never fabricated)', async () => {
+    const http = {
+      get: async (url) => {
+        if (url.includes('/search')) return { data: { items: [{ uid: 's:40~l:46~a:999', displayName: 'X', team: {}, position: {} }] } };
+        return { data: { statistics: { splits: { categories: [{ stats: [{ name: 'avgPoints', value: 10 }] }] } } } };
+      },
+    };
+    const r = await espn.getSeasonAverages('X', 'nba', { http });
+    expect(r.found).toBe(true);
+    expect(r.espnId).toBeNull();
   });
 
   it('degrades to found:false when ESPN errors', async () => {
@@ -56,11 +70,13 @@ describe('resolvePlayerStats wires the ESPN fallback for NBA', () => {
   it('falls back to ESPN when nbaStatsClient is offline → classifies', async () => {
     const r = await svc.resolvePlayerStats('Luka Doncic', 'nba', {
       nbaClient: { getSeasonAvg: async () => { throw new Error('python offline'); } },
-      espnStats: { getSeasonAverages: async () => ({ found: true, team: 'DAL', position: 'G', classifierInput: { ppg: 33, apg: 9, rpg: 8 } }) },
+      espnStats: { getSeasonAverages: async () => ({ found: true, team: 'DAL', position: 'G', classifierInput: { ppg: 33, apg: 9, rpg: 8 }, espnId: '3945274' }) },
     });
     expect(r.found).toBe(true);
     expect(r.team).toBe('DAL');
     expect(r.classifierInput.ppg).toBe(33);
+    // Wave 2A — espnId surfaces through resolvePlayerStats → the snapshot grade.
+    expect(r.espnId).toBe('3945274');
   });
 
   it('found:false when both sources are empty', async () => {

tests/unit/headshotThread.test.js

@@ -0,0 +1,110 @@
+// Wave 2A (WIRING & DATA TRAIN, Step 2) — the headshot id thread.
+//
+// Doctrine: a REAL athlete photo where an id resolves; a team-colored monogram
+// (NEVER a gray silhouette, NEVER a broken image) where it can't. The id is
+// NEVER fabricated — it rides free on the snapshot's per-player stats resolve.
+//
+// This suite locks the four links of the chain:
+//   (a) getHeadshotUrl builds the right per-league CDN URL from a known id
+//   (b) an MLB grade with a resolved MLBAM id → playerId on the strip
+//   (c) an NBA/WNBA grade with a resolved ESPN id → espnId on the strip
+//   (d) a grade with NO id → strip carries no id → PlayerAvatar falls to a
+//       monogram (the null path). Absent beats fabricated.
+
+// The PURE URL core is CommonJS (the .ts re-exports it verbatim); jest can't
+// transform the .ts, so we require the same single source of truth here.
+const { getHeadshotUrl } = require('../../web/src/lib/playerHeadshotUrl');
+const adapter = require('../../web/src/lib/slateAdapter');
+
+describe('(a) getHeadshotUrl — per-league CDN URL from a real id', () => {
+  it('MLB → img.mlbstatic.com via the MLBAM people id', () => {
+    // Aaron Judge = MLBAM 592450.
+    const url = getHeadshotUrl({ sport: 'mlb', playerId: 592450 });
+    expect(url).toBe(
+      'https://img.mlbstatic.com/mlb-photos/image/upload/d_people:generic:headshot:67:current.png/w_213,q_auto:best/v1/people/592450/headshot/67/current',
+    );
+  });
+
+  it('NBA → a.espncdn headshot from the ESPN athlete id (espnId, no playerId)', () => {
+    const url = getHeadshotUrl({ sport: 'nba', espnId: 3945274 });
+    expect(url).toBe(
+      'https://a.espncdn.com/combiner/i?img=/i/headshots/nba/players/full/3945274.png&w=130&h=95',
+    );
+  });
+
+  it('WNBA → a.espncdn headshot from the ESPN athlete id', () => {
+    const url = getHeadshotUrl({ sport: 'wnba', espnId: 4066533 });
+    expect(url).toBe(
+      'https://a.espncdn.com/combiner/i?img=/i/headshots/wnba/players/full/4066533.png&w=130&h=95',
+    );
+  });
+
+  it('dormant NFL/NHL leagues now resolve an ESPN headshot path (cheap correctness)', () => {
+    expect(getHeadshotUrl({ sport: 'nfl', espnId: 3139477 })).toContain('/headshots/nfl/players/full/3139477.png');
+    expect(getHeadshotUrl({ sport: 'nhl', espnId: 3024816 })).toContain('/headshots/nhl/players/full/3024816.png');
+  });
+
+  it('no id at all → the neutral silhouette sentinel (component swaps to monogram)', () => {
+    expect(getHeadshotUrl({ sport: 'mlb' })).toBe('/images/player-silhouette.svg');
+    expect(getHeadshotUrl({ sport: 'soccer', playerId: 123 })).toBe('/images/player-silhouette.svg');
+  });
+});
+
+describe('(b) MLB grade → playerId threads onto the strip', () => {
+  it('carries the MLBAM playerId from the enriched grade to the strip prop group', () => {
+    const props = [{ player: 'Aaron Judge', stat_type: 'hits', line: 1.5, home_team: 'NYY', away_team: 'BOS' }];
+    const gradeIndex = adapter.indexGrades([
+      {
+        player: 'Aaron Judge', stat_type: 'hits', line: 1.5, direction: 'over', grade: 'A',
+        playerId: 592450, team: 'NYY',
+        gradedAt: { line: 1.5, timestamp: '2026-07-10T02:00:00Z' },
+      },
+    ]);
+    const strips = adapter.buildPlayerStripsFromProps(props, gradeIndex, {});
+    expect(strips).toHaveLength(1);
+    expect(strips[0].playerId).toBe(592450);
+    expect(strips[0].espnId).toBeUndefined();
+    // And the id builds the real MLB headshot.
+    expect(getHeadshotUrl({ sport: 'mlb', playerId: strips[0].playerId })).toContain('/people/592450/headshot');
+  });
+});
+
+describe('(c) NBA/WNBA grade → espnId threads onto the strip', () => {
+  it('carries the ESPN espnId from the enriched grade to the strip prop group', () => {
+    const props = [{ player: 'Caitlin Clark', stat_type: 'points', line: 22.5, home_team: 'IND', away_team: 'CHI' }];
+    const gradeIndex = adapter.indexGrades([
+      {
+        player: 'Caitlin Clark', stat_type: 'points', line: 22.5, direction: 'over', grade: 'B+',
+        espnId: 4433403, team: 'IND',
+        gradedAt: { line: 22.5, timestamp: '2026-07-10T02:00:00Z' },
+      },
+    ]);
+    const strips = adapter.buildPlayerStripsFromProps(props, gradeIndex, {});
+    expect(strips).toHaveLength(1);
+    expect(strips[0].espnId).toBe(4433403);
+    expect(strips[0].playerId).toBeUndefined();
+    expect(getHeadshotUrl({ sport: 'wnba', espnId: strips[0].espnId })).toContain('/players/full/4433403.png');
+  });
+});
+
+describe('(d) no resolved id → monogram path (never a fabricated face)', () => {
+  it('a grade with no id → strip has neither playerId nor espnId', () => {
+    const props = [{ player: 'Unknown Prospect', stat_type: 'hits', line: 0.5, home_team: 'NYY', away_team: 'BOS' }];
+    const gradeIndex = adapter.indexGrades([
+      {
+        player: 'Unknown Prospect', stat_type: 'hits', line: 0.5, direction: 'over', grade: 'C',
+        team: 'NYY',
+        gradedAt: { line: 0.5, timestamp: '2026-07-10T02:00:00Z' },
+      },
+    ]);
+    const strips = adapter.buildPlayerStripsFromProps(props, gradeIndex, {});
+    expect(strips[0].playerId).toBeUndefined();
+    expect(strips[0].espnId).toBeUndefined();
+    // PlayerAvatar renders `url = (playerId!=null || espnId!=null) ? … : null`,
+    // so an absent id yields a null url → the branded monogram. Prove the
+    // resolver returns the silhouette sentinel (which the component swaps out)
+    // rather than a fabricated CDN URL when no id is present.
+    expect(getHeadshotUrl({ sport: 'mlb', playerId: strips[0].playerId, espnId: strips[0].espnId }))
+      .toBe('/images/player-silhouette.svg');
+  });
+});

tests/unit/snapshotService.test.js

@@ -115,6 +115,34 @@ describe('runSnapshot (fully injected)', () => {
     expect(cache.store['grades:mlb'].grades).toHaveLength(2);
   });
 
+  it('Wave 2A — threads the resolved athlete id (playerId/espnId) onto the enriched grade', async () => {
+    const cache = memCache();
+    const d = deps(cache);
+    // Judge resolves an MLBAM id; Betts resolves an ESPN id (cross-sport shape).
+    d.resolveStats = async (player) => (player === 'Aaron Judge'
+      ? { found: true, classifierInput: { hr: 34, avg: 0.28, ops: 0.95, k_rate: 28 }, playerId: 592450 }
+      : { found: true, classifierInput: {}, espnId: 4433403 });
+    await svc.runSnapshot('mlb', d);
+    const snap = cache.store['snapshot:mlb:latest'];
+    const judge = snap.grades.find((g) => g.player === 'Aaron Judge');
+    const betts = snap.grades.find((g) => g.player === 'Mookie Betts');
+    expect(judge.playerId).toBe(592450);
+    expect(betts.espnId).toBe(4433403);
+    // grades:{sport} inherits the same ids (GameCard/Explore read from it).
+    const g = cache.store['grades:mlb'].grades.find((x) => x.player === 'Aaron Judge');
+    expect(g.playerId).toBe(592450);
+  });
+
+  it('Wave 2A — no resolved id → enriched grade carries null ids (monogram path)', async () => {
+    const cache = memCache();
+    const d = deps(cache);
+    d.resolveStats = async () => ({ found: false }); // nothing resolves
+    await svc.runSnapshot('mlb', d);
+    const snap = cache.store['snapshot:mlb:latest'];
+    expect(snap.grades[0].playerId).toBeNull();
+    expect(snap.grades[0].espnId).toBeNull();
+  });
+
   it('rotates latest → previous and computes deltas on the second run', async () => {
     const cache = memCache();
     let line = 1.5;