Richer event context: buildup lines from the full play-by-play feed

'X is shown a red card' alone isn't insight — the story is in the
surrounding plays. The ESPN summary carries a ~110-line play-by-play
feed (attempts, fouls, corners, VAR checks) we cached but never used:

- normalizer keeps a trimmed commentary list (schema v3; the boot
  backfill re-stores older matches automatically)
- previews serve it; expanding a timeline event now shows up to four
  feed lines from the three minutes leading in, then the event's own
  description — e.g. Korea's saved attempt and corner right before
  Czechia's counter-goal header, or the foul behind a booking

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/lib/matchEvents.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { eventContext, goalEvents, halfTimeScore, parseEvents } from './matchEvents';
+import { buildup, eventContext, goalEvents, halfTimeScore, parseEvents } from './matchEvents';
 import type { MatchLiveEvent } from './types';
 
 // Real shapes from the ESPN feed (WC 2026 match 2, Korea Republic – Czechia).
@@ -127,6 +127,40 @@ describe('eventContext', () => {
   });
 });
 
+describe('buildup', () => {
+  const goalText = 'Goal! Korea Republic 0, Czechia 1. Ladislav Krejcí (Czechia) header from very close range to the bottom right corner. Assisted by Vladimír Coufal.';
+  const commentary = [
+    { minute: null, text: 'First Half begins.' },
+    { minute: 53, text: 'Foul by Tomás Soucek (Czechia).' },
+    { minute: 56, text: 'Attempt saved. Son Heung-Min (Korea Republic) left footed shot is saved.' },
+    { minute: 56, text: 'Corner, Korea Republic. Conceded by Matej Kovár.' },
+    { minute: 59, text: goalText },
+    { minute: 61, text: 'Attempt missed. Lee Jae-Sung (Korea Republic) header misses to the left.' },
+  ];
+  const [goal] = goalEvents([{ minute: 59, type: 'Goal - Header', team: 'away', text: goalText }]);
+
+  it('returns the lines leading into the event, oldest first', () => {
+    expect(buildup(goal!, commentary).map((c) => c.minute)).toEqual([56, 56]);
+  });
+
+  it('ignores lines older than three minutes before the event', () => {
+    const lines = buildup(goal!, commentary);
+    expect(lines.some((c) => c.minute === 53)).toBe(false);
+  });
+
+  it('caps the number of lines', () => {
+    const noisy = [
+      ...Array.from({ length: 8 }, (_, i) => ({ minute: 58, text: `Pass ${i}.` })),
+      { minute: 59, text: goalText },
+    ];
+    expect(buildup(goal!, noisy, 3)).toHaveLength(3);
+  });
+
+  it('returns nothing when the event opens the feed', () => {
+    expect(buildup(goal!, [{ minute: 59, text: goalText }])).toEqual([]);
+  });
+});
+
 describe('halfTimeScore', () => {
   it('is the last goal score at minute ≤ 45', () => {
     expect(halfTimeScore(parseEvents(realEvents))).toEqual([0, 0]);

src/lib/matchEvents.ts

@@ -145,6 +145,35 @@ export function eventContext(e: ParsedEvent): string | null {
   return ctx;
 }
 
+export interface CommentaryLine { minute: number | null; text: string }
+
+/**
+ * The feed lines leading into an event — the buildup story shown when a
+ * timeline item is expanded (the saved attempt before a counter-goal, the
+ * foul before a card, a VAR check). Anchored on the entry that IS the event
+ * (same text), else the last entry at the event's minute; returns up to
+ * `max` preceding lines no older than three minutes.
+ */
+export function buildup(e: ParsedEvent, commentary: CommentaryLine[], max = 4): CommentaryLine[] {
+  if (e.minute == null || !commentary.length) return [];
+  let anchor = commentary.findIndex((c) => c.text === e.raw);
+  if (anchor === -1) {
+    for (let i = 0; i < commentary.length; i++) {
+      const m = commentary[i]!.minute;
+      if (m != null && m <= e.minute) anchor = i;
+      if (m != null && m > e.minute) break;
+    }
+  }
+  if (anchor <= 0) return [];
+  const out: CommentaryLine[] = [];
+  for (let i = anchor - 1; i >= 0 && out.length < max; i--) {
+    const c = commentary[i]!;
+    if (c.minute == null || c.minute < e.minute - 3) break;
+    out.unshift(c);
+  }
+  return out;
+}
+
 /** Score at half-time: last goal score at minute ≤ 45 (0–0 when none). */
 export function halfTimeScore(parsed: ParsedEvent[]): [number, number] {
   let ht: [number, number] = [0, 0];

src/lib/types.ts

@@ -159,6 +159,8 @@ export interface MatchPreview {
   liveStats: { home: Record<string, string>; away: Record<string, string> } | null;
   /** Live/finished event timeline (goals, cards, subs). */
   events: MatchLiveEvent[];
+  /** Full play-by-play feed, kickoff first — buildup context for events. */
+  commentary: { minute: number | null; text: string }[];
   /** Honest note on which data layers are populated yet. */
   dataNote: string;
   updatedAt: number | null;