@claudinho/core 0.11.2 → 0.12.0

package/dist/index.d.ts

@@ -153,11 +153,27 @@ type Stage = 'GROUP' | 'R32' | 'R16' | 'QF' | 'SF' | '3P' | 'F' | 'FRIENDLY' | '
 type Status = 'SCHEDULED' | 'LIVE' | 'HT' | 'FT' | 'POSTPONED' | 'CANCELLED';
 /** Match outcome from the home team's perspective. */
 type Outcome = 'H' | 'D' | 'A';
-/** A discrete in-match event (provider-dependent; often absent on free tiers). */
+/**
+ * One of a match's goals or cards, as the provider listed it (ESPN's
+ * `competitions[0].details`, read by the grammar in `trust/espn.ts` and sealed
+ * by `sealEvent` in `trust/match.ts`, on the feed and the cache path alike).
+ * Key order is the serialized order.
+ */
 interface MatchEvent {
+    /** The kind. `SUB` stays in the type; ESPN's scoreboard never produces one. */
     type: 'GOAL' | 'OWN_GOAL' | 'PEN' | 'YELLOW' | 'RED' | 'SUB';
+    /** The minute the provider's clock showed: `90` for `90'+3'`. */
     minute: number;
+    /** Added time past `minute` (`3` for `90'+3'`), 1 to 30; absent when none. */
+    added?: number;
+    /**
+     * The side the event belongs to: the side a goal COUNTED for (an own goal
+     * included), the side a card was shown to. The identity; `teamCode` is a label.
+     */
+    side: 'home' | 'away';
+    /** That side's code, a display label. */
     teamCode: string;
+    /** The player, when the provider names exactly one of the expected team. */
     player?: string;
 }
 /** A single fixture/result — the central entity. */
@@ -201,7 +217,13 @@ interface Match {
     /** Live match minute when in progress. */
     minute?: number;
     status: Status;
-    /** Goals/cards when the provider supplies them. */
+    /**
+     * The provider's goals and cards that could be read, in time order (minute,
+     * then added time). Never a claim that the list is every goal: a detail the
+     * grammar cannot read is left out, and a live timeline lags its score by
+     * nature. None on a match with no score (scheduled, postponed, cancelled);
+     * the key is absent when none was read.
+     */
     events?: MatchEvent[];
     /**
      * Winner's team code when the provider marks one (e.g. ESPN `competitor.winner`
@@ -279,6 +301,27 @@ type Lang = 'en' | 'es' | 'pt' | 'fr';
 declare function normalizeLang(lang?: string): Lang;
 /** Translate a message key with optional `{placeholder}` interpolation. */
 declare function t(lang: string | undefined, key: string, vars?: Record<string, string>): string;
+/**
+ * The ten words of the plugin's moments, as `claudinho ambient --json` sends
+ * them (`words`), in this order: core's `moment.*` keys in one language.
+ * `goalFor` and `win` are templates holding `{team}` once, which the plugin
+ * fills with the record's own names; names, scores and minutes are never
+ * translated.
+ */
+interface MomentWords {
+    readonly goal: string;
+    readonly ownGoal: string;
+    readonly ownGoalDetail: string;
+    readonly goalFor: string;
+    readonly goals: string;
+    readonly scoreUpdated: string;
+    readonly penalties: string;
+    readonly fullTime: string;
+    readonly win: string;
+    readonly draw: string;
+}
+/** The moment words in `lang` (an unsupported one is English), the templates left unfilled. */
+declare function momentWords(lang: string | undefined): MomentWords;
 /**
  * Localized stage label, from the match (its stage, its group letter under the
  * group stage, and the words an OTHER stage carries). An `OTHER` stage prints
@@ -384,6 +427,42 @@ declare function padVisible(s: string, width: number): string;
  */
 declare function withFlag(text: string, flag: string | undefined, side: 'home' | 'away'): string;
 
+interface TimelineOptions {
+    /** The reader's language (en/es/pt/fr); English when absent. */
+    readonly lang?: string;
+    /** Whether a nation's flag is printed beside its code (a club has none either way). */
+    readonly flags: boolean;
+}
+/** One part of a timeline row: its text, and `strong` on the player. */
+interface TimelinePart {
+    readonly text: string;
+    readonly style?: 'strong';
+}
+/**
+ * The match's events as rows of parts; `[]` when it has none. Each row is
+ * the aligned columns as one plain part (two spaces, the minute, the marker,
+ * one space and the localized kind word, the side's label), then, when the
+ * provider named a player, two spaces and the player as one `strong` part.
+ * Joined, a row is its {@link timelineRows} line.
+ */
+declare function timelineParts(match: Match, opts: TimelineOptions): TimelinePart[][];
+/** The match's events as aligned text rows ({@link timelineParts} joined); `[]` when it has none. */
+declare function timelineRows(match: Match, opts: TimelineOptions): string[];
+/**
+ * The goal that made the record's score, PROVEN, or `null`. The record's
+ * scoring events, counted per side in their order (an own goal for the side
+ * it credited, which is the event's `side`), must equal its regulation score:
+ * then the timeline is whole and its last scoring event is the goal that made
+ * this score. Anything else proves nothing (a timeline that lags the score, a
+ * disallowed goal still listed, no score, no scoring event): the first scorer
+ * is never named for a second goal. Two scoring events identical in type,
+ * minute, added time, side and player prove nothing either: the same goal
+ * listed twice beside a timeline that lags would count as two. The ambient
+ * view's `lastGoal`, written by the refresher on each live record it
+ * publishes.
+ */
+declare function provenLastGoal(match: Match): MatchEvent | null;
+
 /** Outcome (home perspective) from a final/looking scoreline. */
 declare function outcomeFromScore(home: number, away: number): Outcome;
 /** Is the match currently in play (including halftime)? */
@@ -871,8 +950,9 @@ declare function fixturesByGroup(group: string, fixtures?: Match[]): Match[];
 /**
  * Eligible to be "the next match": the kickoff is still ahead AND the match is
  * still going to be played. ONE predicate for every selector (`next`, the
- * statusline countdown, the knockout-fixture cache, the market fixture, the
- * refresher cadence) — a cancelled or postponed fixture keeps its kickoff, so
+ * knockout-fixture cache, the market fixture, the refresher cadence; the
+ * statusline countdown asks it for a kickoff strictly ahead and also names a
+ * DUE fixture, the CLI's `isDue`) — a cancelled or postponed fixture keeps its kickoff, so
  * a time-only check advertised it as the next game (audit A07). Finished is
  * deliberately NOT a clause: under a real clock a finished match never has a
  * future kickoff, and excluding it only changed seeded-clock replays of an
@@ -1683,7 +1763,7 @@ interface KnockoutFixturesResult {
 /**
  * The RESOLVED upcoming knockout fixtures from the live overlay — the data the
  * hot-path statusline can't fetch itself but needs to show a real next-match
- * countdown (e.g. "🇲🇽 vs 🇪🇨 in 2d") instead of a 🏳️ placeholder. The cold-path
+ * countdown (e.g. "⚽ 🇲🇽 vs 🇪🇨 in 2d") instead of a 🏳️ placeholder. The cold-path
  * refresher calls this and caches the result; the statusline reads the cache.
  *
  * Returns only fixtures where BOTH sides are resolved (neither is the 🏳️ placeholder) and kickoff
@@ -1794,6 +1874,8 @@ declare function getScheduleAhead(adapter: ProviderAdapter, now?: Date): Promise
  * an adjacent bucket. Adapters without a window fetch fall back to `fetchLive()`.
  */
 declare function getLiveMatches(adapter: ProviderAdapter, now?: Date): Promise<LiveResult>;
+/** The finished records a live read returns, at most (the refresher's record of play keeps as many). */
+declare const MAX_LIVE_FINISHED = 64;
 /** A live read with the answer's own account of itself: what the refresher decides from. */
 interface LiveReadResult extends LiveResult {
     /**
@@ -1802,14 +1884,30 @@ interface LiveReadResult extends LiveResult {
      * whole and holds no match in play does not prove none is.
      */
     complete: boolean;
+    /**
+     * The window's records with status `FT` that hold a score, as the adapter
+     * sealed them, asked of the whole window before the in-play filter: the ids
+     * the caller passed as `seen` first, in the window's order, then the others,
+     * at most {@link MAX_LIVE_FINISHED}. `[]` for a failed read. The evidence of
+     * full time for a match the refresher saw in play; never on
+     * {@link getLiveMatches}' result.
+     */
+    finished: Match[];
+    /**
+     * The cap left finished records out: an id the caller saw that is absent
+     * from `finished` may then be one of them, so its absence decides nothing.
+     */
+    finishedTruncated: boolean;
 }
 /**
  * {@link getLiveMatches}, keeping the window's `complete` verdict (read from
- * the window's result BEFORE the in-play filter makes a new array). For the
- * cold-path refresher, which keeps polling after a match was seen in play
- * until a WHOLE read holds none.
+ * the window's result BEFORE the in-play filter makes a new array), and the
+ * window's finished records (`finished`, chosen ids-first by `seen`, the ids
+ * the refresher's record of play holds as seen in play). For the cold-path
+ * refresher, which keeps polling after a match was seen in play until a WHOLE
+ * read holds none.
  */
-declare function getLiveRead(adapter: ProviderAdapter, now?: Date): Promise<LiveReadResult>;
+declare function getLiveRead(adapter: ProviderAdapter, now?: Date, seen?: readonly string[]): Promise<LiveReadResult>;
 
 /** A roster team plus its group letter (A–L). */
 interface TeamInfo extends Team {
@@ -1951,6 +2049,15 @@ interface BoundedList<T> {
  * make an unbounded traversal safe. `takeBounded` is the one that bounds work.
  */
 declare function bounded<T>(items: readonly T[], max: number, complete?: boolean): BoundedList<T>;
+/**
+ * Take at most `max` items from something that may not be an array at all,
+ * BEFORE any per-item work happens.
+ *
+ * This is the work bound. Mapping, sorting or sanitizing first and slicing
+ * afterwards is what made a 4,000-row group cost 300ms to return 32, and a
+ * 100k-event record cost 5.3s on a 150ms surface.
+ */
+declare function takeBounded<T>(value: unknown, max: number): T[];
 
 /**
  * The vocabulary for "we could not use this".
@@ -2514,7 +2621,7 @@ declare const DEFAULT_MAX_AGE_MS: number;
  * "markets favor X 100%" after full time reads as a bug, not information.
  * An unparseable kickoff fails open (the reliability gate still applies).
  */
-declare function marketRelevant(match: Match, now?: Date): boolean;
+declare function marketRelevant(match: Match, now: Date): boolean;
 /**
  * Re-scale outcome probabilities so the positive ones sum to 1. This removes
  * market "vig" (raw prices sum to >1) and is scale-agnostic: inputs may be
@@ -2886,6 +2993,15 @@ declare function isPinnedSide(side: Team, pin: {
     readonly code: string;
     readonly name: string;
 }): boolean;
+/**
+ * THE constructor of a `MatchEvent`, on the feed path (the candidates the ESPN
+ * detail grammar built) and the cache path alike. An event with no side, a
+ * side that is neither, an unreadable minute or an added time outside 1..30 is
+ * refused (`null`); the match stands. Keys in the order `MatchEvent` declares
+ * them. Exported for the one other reader of an event, the ambient view, which
+ * re-seals the `lastGoal` the refresher stored on a cached live record.
+ */
+declare function sealEvent(raw: unknown): MatchEvent | null;
 /**
  * Validate candidate parts into a Match, or say why not.
  *
@@ -3252,12 +3368,41 @@ declare function bracketCapability(competition: string, table?: readonly Competi
  *   - a selected competition: an {@link AmbientView}.
  */
 
+/**
+ * One part of the band's line (`lineParts`): a run of its text, `strong` for a
+ * score token the fit kept whole. The parts' texts joined are the line.
+ */
+interface AmbientLinePart {
+    readonly text: string;
+    readonly style?: 'strong';
+}
+/** The two names the hook's line prints for a record (a nation's roster name on the bundled competition). */
+interface AmbientNames {
+    readonly home: string;
+    readonly away: string;
+}
+/**
+ * A finished match as the ambient view lists it (`finished`): the sealed
+ * record (status `FT`, its final score), as a live one is serialized, with:
+ */
+type AmbientFinishedMatch = Match & {
+    /**
+     * The side of the SAVED pin (`claudinho follow <alias> --team`, by core's
+     * `isPinnedSide`), or `null`: never `CLAUDINHO_TEAM`, which only orders.
+     */
+    readonly pinnedSide: 'home' | 'away' | null;
+    /** The names the hook's line prints for it. */
+    readonly names: AmbientNames;
+    /** The hook's own line for it, `(FT)` in the minute's place. */
+    readonly line: string;
+};
 /**
  * A live match as the ambient view lists it: the sealed record, as the other
  * `--json` twins serialize a `Match` (`status`, the `score` object, `shootout`
  * after a shootout, `Team.id` where the cache holds it, a nation's generated
  * `flag`, no `flag` key on a club), with no `events` key (the ambient reader
- * never seals a timeline), and two booleans about the reader's own team:
+ * never seals a timeline), and what it says about the reader's own team, the
+ * names and the last goal:
  */
 type AmbientMatch = Match & {
     /**
@@ -3271,6 +3416,10 @@ type AmbientMatch = Match & {
      * World Cup's nations); whatever `CLAUDINHO_TEAM` prefers.
      */
     readonly pinned: boolean;
+    /** Which side is the SAVED pin's (by core's `isPinnedSide`), or `null`: never `CLAUDINHO_TEAM`'s. */
+    readonly pinnedSide: 'home' | 'away' | null;
+    /** The names the hook's line prints for it (a nation's roster name on the bundled competition). */
+    readonly names: AmbientNames;
     /**
      * The hook's own line for this record, as `claudinho hook` prints it (the
      * names, pinned to the World Cup's roster on the bundle, each with its flag
@@ -3279,17 +3428,40 @@ type AmbientMatch = Match & {
      * never composes one.
      */
     readonly line: string;
+    /**
+     * The goal that made the record's score, PROVEN by the refresher (its
+     * scoring events counted per side equal the score: core's
+     * `provenLastGoal`), stored on the cached record and re-sealed by the
+     * reader with core's `sealEvent` and kept only as a goal, an own goal or a
+     * penalty whose `teamCode` is the code of the side its `side` names, a side
+     * that has scored (its regulation score at least 1); `null`
+     * when nothing is proven or the stored value is anything else.
+     */
+    readonly lastGoal: MatchEvent | null;
 };
 /** The ambient view of a selected competition, its keys in this order. */
 interface AmbientView {
     /**
-     * The statusline's line, as `claudinho prompt` prints it (the same reader,
-     * the same options), fitted to `--columns N` when given: whole matches are
-     * kept while they fit and the rest counted in the `+N` (or `+more`) suffix,
-     * which is never cut while the width holds it; below the suffix's own width
-     * the line is the width's cut, never wider than asked.
+     * The statusline's line rendered in `lang` (the same reader and the same
+     * options as `claudinho prompt`, which prints it in English), fitted to
+     * `--columns N` when given: whole matches are kept while they fit and
+     * the rest counted in the `+N` (or `+more`) suffix, which is never cut
+     * while the width holds it; below the suffix's own width
+     * the line is the width's cut, never wider than asked. Its own tokens are in
+     * `lang` (the countdown, the syncing phrase, the live segment's half-time
+     * and live words); the overflow marker (`+N`, `+more`), the World Cup's
+     * sign-off and nothing known (`⚽ —`) are English in every language, so
+     * `idle` and `empty` say what they say in every language.
      */
     readonly line: string;
+    /**
+     * The line as parts, built by the fitter as it places each shown score
+     * token: their texts joined are `line` exactly, a score token the fit kept
+     * whole is `strong`, one it cut is not. One plain part, the line itself, on
+     * the countdown, the syncing line, nothing known and the sign-off, and
+     * whenever the parts would not join to the line.
+     */
+    readonly lineParts: readonly AmbientLinePart[];
     /**
      * The line is the one long-lived line, the edition's sign-off (the World
      * Cup's, once every bundled window has closed): nothing changes until the
@@ -3322,6 +3494,18 @@ interface AmbientView {
      * listed, best effort, as the line shows it, and is never current.
      */
     readonly live: BoundedList<AmbientMatch>;
+    /**
+     * The matches the refresher SAW in play that a whole read then returned
+     * finished (the snapshot's record of play), each for 10 minutes from the
+     * read that first saw it finished, judged by the reader's clock (a stamp in
+     * the future is not believed), whatever the snapshot's display window (the
+     * refresher stops polling once the last match ends, so the snapshot ages
+     * past it while an entry is still inside its own 10 minutes); never one the
+     * live list holds. Listed only from a snapshot whose live read was whole
+     * (`liveComplete: true`); otherwise `[]`, which then says nothing. At most
+     * 64. Absence from it never means a match is over.
+     */
+    readonly finished: readonly AmbientFinishedMatch[];
     /**
      * The live list is a believed snapshot's inside its display window (its
      * stamp's age, by the reader's own rule, is finite and short of the window),
@@ -3337,7 +3521,9 @@ interface AmbientView {
     /**
      * The fixture the statusline's countdown names (its resolved pairing; the
      * preference's first), whether or not a match is in play now; `null` when
-     * there is none to count down to. A fixture ahead, never one in play.
+     * there is none to count down to. A fixture ahead, or a DUE one (still
+     * scheduled, its kickoff passed by at most 30 minutes, not held by the
+     * snapshot's record of play: the line reads "now"); never one in play.
      */
     readonly next: Match | null;
     /**
@@ -3357,6 +3543,19 @@ interface AmbientView {
     readonly pickUnreadable?: true;
     /** The selection, as every `--json` answer carries it (core `selectionExtras`). */
     readonly competition: CompetitionKey;
+    /**
+     * The CLI's resolved language (`--lang`, `CLAUDINHO_LANG`, `LANG`'s language
+     * part, each only when it is one of the four, else `en`), the language of
+     * `line`, `lineParts` and `words`. `context`, `attribution`, `disclaimer`
+     * and each record's `line` stay English in every language.
+     */
+    readonly lang: Lang;
+    /**
+     * The plugin's moment words in `lang` (core's `moment.*` keys, `momentWords`):
+     * `goalFor` and `win` templates holding `{team}` once, for the plugin to
+     * fill with a record's own `names`.
+     */
+    readonly words: MomentWords;
     /** The snapshot says its last refresh failed (`false` with no snapshot). */
     readonly degraded: boolean;
     /** The provider the snapshot was read from, whatever its stamp; `null` with no snapshot. */
@@ -3374,6 +3573,20 @@ interface AmbientView {
     readonly staleAfter: string | null;
     /** The non-affiliation sentence, core's `DISCLAIMER`. */
     readonly disclaimer: string;
+    /**
+     * The provider's attribution sentence, in English as every ambient string:
+     * core's `live.data` copy with `liveSourceLabel(source)` (`Live data:
+     * ESPN`), when the snapshot names a provider (`source` is a string) AND
+     * the line is neither the sign-off (`idle`) nor nothing known (`empty`);
+     * `null` otherwise: no snapshot, the sign-off (made from the bundled clock),
+     * nothing known. `degraded` does not decide: a degraded snapshot still shows
+     * a live row an earlier read served, or a countdown to a fixture discovery
+     * read; nor does a read that was not whole. A limit: on the bundled
+     * competition, a countdown made from the bundled skeleton (before its
+     * knockout pairings resolve) would be attributed too; unreachable while that
+     * edition is over.
+     */
+    readonly attribution: string | null;
 }
 
 /** The two v1 snippet shapes. `social` is the rich card; `compact` is one terse line per match. */
@@ -4067,4 +4280,4 @@ declare function lookAtEntry(path: string): FileEntry;
  */
 declare function lookAtOwnFile(path: string, maxBytes: number): OwnFile;
 
-export { type AmbientMatch, type AmbientView, BRACKET_STAGE_ORDER, BUNDLE_COMPETITION, type BatchResolution, type BetweenEditions, type BoundedList, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketShareCard, type BracketTopology, type BracketView, type BuildSignalInput, COMPETITION_KIND, COUNTDOWN_NOW, type Capabilities, type Capability, type ChosenBy, type ClubResolution, type CompetitionEntry, type CompetitionKey, type CompetitionKind, type CompetitionSelection, DEFAULT_COMPETITION, DEFAULT_COOLDOWN_MS, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, DISCLAIMER, type DayAttribution, type DerivedTables, EARLIER_RECORD_NOTE, EspnAdapter, type EspnAdapterOptions, FAN_PROJECT, FLAVOR_BANKS, FLAVOR_LEVELS, FLAVOR_MOMENTS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FetchMeta, type FetchWindowOptions, type FileEntry, type Flair, type FlairOpts, type FlavorBank, type FlavorLevel, type Moment as FlavorMoment, type FlavorOpts, type FormatOpts, type GroupStandings, KNOCKOUT_EXTRA_TIME_MS, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type ListedCompetition, type LiveReadResult, type LiveResult, MARKETS_SCOPE_NOTE, MARKET_COMPETITIONS, MAX_CONFIG_BYTES, MAX_COOLDOWN_MS, MAX_LABEL_COLUMNS, MAX_RESPONSE_BYTES, MAX_SCHEDULE_INDEX, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type MatchShareCard, NO_BRACKET, type NextFixtureResult, type NoConfigReason, type Outcome, type OwnFile, type ParseResult, type Pin, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, RALLY_CRIES, type RallyCry, type RallyPin, type ReadAccount, type ResolvedParticipant, ResponseTooLargeError, type Roster, SCHEDULE_AHEAD_DAYS, SCHEDULE_LOOKBACK_DAYS, SEASON_SLUG, SHARE_DISCLAIMER, SHARE_HASHTAG, STANDINGS_SHAPE, SUPPORTED, type ScheduleAheadResult, type ScheduleEntry, type SeasonInfo, type SelectedCompetition, type Selection, type ShareBracketInput, type ShareBracketOptions, type ShareCardContext, type ShareCardMarket, type ShareCardView, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type SmallFile, type Stage, type StandingRow, type StandingsResult, type Status, TABLE_KEY_ARG, TEAM_KIND, type TableData, type TableShareCard, type Team, type TeamInfo, type TeamKind, type TeamLookup, type UserConfig, type UserConfigRead, type VerdictExtras, type VerdictSource, allFixtures, allTeams, ambiguous, asFlavorLevel, attachFetchMeta, bounded, bracketCapability, bracketShareCard, buildBracketTopology, buildBracketView, buildMarketSignal, bundleApplies, bundleSeasonYear, byKickoff, cacheDirFor, cacheableKeys, capabilitiesOf, competitionBase, competitionKind, competitionLabel, competitionValue, computeStandings, configPath, countdown, countdownPhrase, currentOrNextFixtureForTeam, dateNoneRead, dateNoneReadSentence, dateShareCard, dateUnreached, dateUnreachedSentence, dayAttribution, definitiveNone, deriveFavorite, deriveTables, disclaimerLine, displayWidth, emptyBatch, entryOf, favoriteStrength, fetchMeta, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, flavorsFor, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getLiveRead, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getScheduleAhead, getStandings, groups, hasLiveWindow, hasSaneDistribution, humanLabel, isCacheable, isFinished, isFlavorLevel, isHumanLabel, isKnockoutStage, isKnownSource, isLive, isMexicoNationalTeam, isPinnedSide, isPlaceholderSide, isReliableMarketSignal, isStaleSignal, isTeam, isTournamentWindowOver, isUpcoming, isValidDate, isValidTimeZone, joinSegments, knockoutWindow, listCompetitions, liveNoneRead, liveNoneReadSentence, liveShareCard, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookAtEntry, lookAtOwnFile, lookAtSmallFile, lookupTeam, makeAdapter, makeMarketProvider, malformed, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketDisplayable, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketScopeVerdict, marketSignalRendersFor, marketSourceLabel, marketsCoverCompetition, marketsNoneRead, marketsNoneReadNote, marketsNoneReadSentence, matchFlair, matchFlairs, matchFlavor, matchKey, matchLocation, matchNoneReadSentence, matchShareCard, matchWindowSentence, mergeLive, modeLine, nationArg, nationToFlag, nationToRegion, nextFixtureForPin, nextFixtureForTeam, nextHorizonSentence, nextNoneReadSentence, nextShareCard, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseCachedMarketSignal, parseCachedMatch, parseCachedMatches, parseCachedScheduleIndex, parseStandings, parseTeamSlot, parsedValue, pinUnder, productFlag, rallyCryFor, rallyEntryFor, readJsonBounded, readSmallFile, readUserConfig, requestClock, resolveClub, resolveCompetition, resolveMarketSource, resolveTz, resolvedValues, retryAfterMs, rosterFor, sanitizeBundledFixture, savedSlug, scheduleEntryOf, scheduleSpan, scoreline, sealMarketSignal, sealMatch, sealScheduleEntry, sealSeason, selectOne, selectedCompetition, selectionExtras, selectionRefusal, selectionVerdict, servedExtras, stageLabel, stageLabelI18n, standingsShapeOf, statesPartial, t, tableData, tableKeyArg, tableShareCard, tableTitle, teamKind, truncateVisible, unresolved, unservedSentence, valid, verdictExtras, verdictNotice, verdictQualifiers, withFlag };
+export { type AmbientFinishedMatch, type AmbientLinePart, type AmbientMatch, type AmbientNames, type AmbientView, BRACKET_STAGE_ORDER, BUNDLE_COMPETITION, type BatchResolution, type BetweenEditions, type BoundedList, type BracketFormatOpts, type BracketMatchNode, type BracketMatchView, type BracketResult, type BracketShareCard, type BracketTopology, type BracketView, type BuildSignalInput, COMPETITION_KIND, COUNTDOWN_NOW, type Capabilities, type Capability, type ChosenBy, type ClubResolution, type CompetitionEntry, type CompetitionKey, type CompetitionKind, type CompetitionSelection, DEFAULT_COMPETITION, DEFAULT_COOLDOWN_MS, DEFAULT_FLAVOR, DEFAULT_MAX_AGE_MS, DISCLAIMER, type DayAttribution, type DerivedTables, EARLIER_RECORD_NOTE, EspnAdapter, type EspnAdapterOptions, FAN_PROJECT, FLAVOR_BANKS, FLAVOR_LEVELS, FLAVOR_MOMENTS, FakeMarketProvider, type FakeMarketProviderOptions, type FavoriteStrength, type FetchMeta, type FetchWindowOptions, type FileEntry, type Flair, type FlairOpts, type FlavorBank, type FlavorLevel, type Moment as FlavorMoment, type FlavorOpts, type FormatOpts, type GroupStandings, KNOCKOUT_EXTRA_TIME_MS, KNOWN_SOURCES, type KnockoutFixturesResult, LIVE_WINDOW_MS, type Lang, type LedgerRow, type ListedCompetition, type LiveReadResult, type LiveResult, MARKETS_SCOPE_NOTE, MARKET_COMPETITIONS, MAX_CONFIG_BYTES, MAX_COOLDOWN_MS, MAX_LABEL_COLUMNS, MAX_LIVE_FINISHED, MAX_RESPONSE_BYTES, MAX_SCHEDULE_INDEX, type MapContext, type MarketFavorite, type MarketMapping, type MarketMappingTable, type MarketOutcome, type MarketOutcomeKind, type MarketProvider, type MarketSignal, type MarketSignalOptions, type MarketSignalsResult, type Match, type MatchByIdResult, type MatchEvent, type MatchShareCard, type MomentWords, NO_BRACKET, type NextFixtureResult, type NoConfigReason, type Outcome, type OwnFile, type ParseResult, type Pin, PolymarketProvider, type PolymarketProviderOptions, type ProviderAdapter, type ProviderCapabilities, ProviderError, type ProviderErrorKind, type PunditPick, RALLY_CRIES, type RallyCry, type RallyPin, type ReadAccount, type ResolvedParticipant, ResponseTooLargeError, type Roster, SCHEDULE_AHEAD_DAYS, SCHEDULE_LOOKBACK_DAYS, SEASON_SLUG, SHARE_DISCLAIMER, SHARE_HASHTAG, STANDINGS_SHAPE, SUPPORTED, type ScheduleAheadResult, type ScheduleEntry, type SeasonInfo, type SelectedCompetition, type Selection, type ShareBracketInput, type ShareBracketOptions, type ShareCardContext, type ShareCardMarket, type ShareCardView, type ShareSnippetInput, type ShareSnippetOptions, type ShareStyle, type ShareTableInput, type SlotRef, type SmallFile, type Stage, type StandingRow, type StandingsResult, type Status, TABLE_KEY_ARG, TEAM_KIND, type TableData, type TableShareCard, type Team, type TeamInfo, type TeamKind, type TeamLookup, type TimelineOptions, type TimelinePart, type UserConfig, type UserConfigRead, type VerdictExtras, type VerdictSource, allFixtures, allTeams, ambiguous, asFlavorLevel, attachFetchMeta, bounded, bracketCapability, bracketShareCard, buildBracketTopology, buildBracketView, buildMarketSignal, bundleApplies, bundleSeasonYear, byKickoff, cacheDirFor, cacheableKeys, capabilitiesOf, competitionBase, competitionKind, competitionLabel, competitionValue, computeStandings, configPath, countdown, countdownPhrase, currentOrNextFixtureForTeam, dateNoneRead, dateNoneReadSentence, dateShareCard, dateUnreached, dateUnreachedSentence, dayAttribution, definitiveNone, deriveFavorite, deriveTables, disclaimerLine, displayWidth, emptyBatch, entryOf, favoriteStrength, fetchMeta, fixturesByDate, fixturesByGroup, fixturesByTeam, fixturesInLiveWindow, flagEmoji, flavorsFor, formatBracketCompactLine, formatBracketList, formatBracketMatchLine, formatBracketTree, formatDate, formatKickoff, formatShareBracket, formatShareSnippet, formatShareTable, formatTime, getBracket, getKnockoutFixtures, getLiveMatches, getLiveRead, getMarketSignal, getMarketSignals, getMatchById, getMatchesForDate, getNextFixtureForTeam, getScheduleAhead, getStandings, groups, hasLiveWindow, hasSaneDistribution, humanLabel, isCacheable, isFinished, isFlavorLevel, isHumanLabel, isKnockoutStage, isKnownSource, isLive, isMexicoNationalTeam, isPinnedSide, isPlaceholderSide, isReliableMarketSignal, isStaleSignal, isTeam, isTournamentWindowOver, isUpcoming, isValidDate, isValidTimeZone, joinSegments, knockoutWindow, listCompetitions, liveNoneRead, liveNoneReadSentence, liveShareCard, liveSourceLabel, liveWindowMsFor, loadBracketTopology, localDate, lookAtEntry, lookAtOwnFile, lookAtSmallFile, lookupTeam, makeAdapter, makeMarketProvider, malformed, mapEspnEvent, mapsCleanly, marketAttributionText, marketBlock, marketDisplayable, marketFavoriteText, marketFixtureForTeam, marketLine, marketProbabilityText, marketRelevant, marketScopeVerdict, marketSignalRendersFor, marketSourceLabel, marketsCoverCompetition, marketsNoneRead, marketsNoneReadNote, marketsNoneReadSentence, matchFlair, matchFlairs, matchFlavor, matchKey, matchLocation, matchNoneReadSentence, matchShareCard, matchWindowSentence, mergeLive, modeLine, momentWords, nationArg, nationToFlag, nationToRegion, nextFixtureForPin, nextFixtureForTeam, nextHorizonSentence, nextNoneReadSentence, nextShareCard, normalizeLang, normalizeOutcomes, outcomeFromScore, padVisible, parseCachedMarketSignal, parseCachedMatch, parseCachedMatches, parseCachedScheduleIndex, parseStandings, parseTeamSlot, parsedValue, pinUnder, productFlag, provenLastGoal, rallyCryFor, rallyEntryFor, readJsonBounded, readSmallFile, readUserConfig, requestClock, resolveClub, resolveCompetition, resolveMarketSource, resolveTz, resolvedValues, retryAfterMs, rosterFor, sanitizeBundledFixture, savedSlug, scheduleEntryOf, scheduleSpan, scoreline, sealEvent, sealMarketSignal, sealMatch, sealScheduleEntry, sealSeason, selectOne, selectedCompetition, selectionExtras, selectionRefusal, selectionVerdict, servedExtras, stageLabel, stageLabelI18n, standingsShapeOf, statesPartial, t, tableData, tableKeyArg, tableShareCard, tableTitle, takeBounded, teamKind, timelineParts, timelineRows, truncateVisible, unresolved, unservedSentence, valid, verdictExtras, verdictNotice, verdictQualifiers, withFlag };

package/dist/index.js

@@ -332,6 +332,13 @@ var EN = {
   "status.fullTime": "full-time",
   "status.postponed": "postponed",
   "status.cancelled": "cancelled",
+  // A timeline row's kind word (core `timelineRows`).
+  "event.goal": "Goal",
+  "event.ownGoal": "Own goal",
+  "event.penalty": "Penalty",
+  "event.yellow": "Yellow card",
+  "event.red": "Red card",
+  "event.sub": "Substitution",
   "live.title": "Live now",
   "today.title": "Today's matches",
   "today.on": "Matches",
@@ -340,6 +347,23 @@ var EN = {
   "next.in": "in {countdown}",
   // A kickoff that has passed, where the countdown would say "in" (core `countdownPhrase`).
   "countdown.now": "now",
+  // The ambient line's syncing phrase (`claudinho ambient --json` alone; the
+  // statusline's own `prompt` stays English).
+  "ambient.syncing": "live \xB7 syncing\u2026",
+  // The plugin's moment words, sent by `claudinho ambient --json` as `words`
+  // (`{team}` a template the plugin fills with the record's own names). Each
+  // at most 40 characters; `{team}` once in `moment.goalFor` and `moment.win`
+  // and nowhere else, or the plugin falls back to its English words.
+  "moment.goal": "GOAL!",
+  "moment.ownGoal": "Own goal",
+  "moment.ownGoalDetail": "own goal",
+  "moment.goalFor": "Goal for {team}",
+  "moment.goals": "Goals",
+  "moment.scoreUpdated": "Score updated",
+  "moment.penalties": "Penalties",
+  "moment.fullTime": "Full time",
+  "moment.win": "{team} win",
+  "moment.draw": "Draw",
   // A title that introduces the lines below it (the MCP text).
   heading: "{title}:",
   // A list's empty state and the outage lines: the CLI's sentences, the MCP
@@ -351,6 +375,7 @@ var EN = {
   "feed.earlierRecord": "Live state could not be refreshed \u2014 showing the provider's earlier record.",
   "next.none": "No upcoming fixture found for {team}.",
   "match.none": "No match found with id {id}.",
+  "match.kickoff": "Kickoff",
   // The MCP text's own sentences for these states (the CLI says `live.degraded`
   // there): they keep the team or the id the answer is about.
   "next.unreachable": "Couldn't reach the data provider \u2014 no upcoming fixture confirmed for {team}.",
@@ -428,6 +453,12 @@ var ES = {
   "status.fullTime": "finalizado",
   "status.postponed": "aplazado",
   "status.cancelled": "cancelado",
+  "event.goal": "Gol",
+  "event.ownGoal": "Gol en contra",
+  "event.penalty": "Penal",
+  "event.yellow": "Tarjeta amarilla",
+  "event.red": "Tarjeta roja",
+  "event.sub": "Cambio",
   "live.title": "En vivo",
   "today.title": "Partidos de hoy",
   "today.on": "Partidos",
@@ -435,6 +466,17 @@ var ES = {
   "next.label": "Pr\xF3ximo partido de {team}",
   "next.in": "en {countdown}",
   "countdown.now": "ahora",
+  "ambient.syncing": "en vivo \xB7 sincronizando\u2026",
+  "moment.goal": "\xA1GOL!",
+  "moment.ownGoal": "Gol en contra",
+  "moment.ownGoalDetail": "gol en contra",
+  "moment.goalFor": "Gol de {team}",
+  "moment.goals": "Goles",
+  "moment.scoreUpdated": "Marcador corregido",
+  "moment.penalties": "Penales",
+  "moment.fullTime": "Final",
+  "moment.win": "Gana {team}",
+  "moment.draw": "Empate",
   heading: "{title}:",
   "today.none": "No hay partidos para esta fecha.",
   "live.none": "No hay partidos en juego ahora mismo.",
@@ -443,6 +485,7 @@ var ES = {
   "feed.earlierRecord": "No se pudo actualizar el estado en vivo \u2014 se muestra el registro anterior del proveedor.",
   "next.none": "No se encontr\xF3 pr\xF3ximo partido para {team}.",
   "match.none": "No se encontr\xF3 partido con id {id}.",
+  "match.kickoff": "Inicio",
   "next.unreachable": "No se pudo contactar al proveedor de datos \u2014 ning\xFAn pr\xF3ximo partido confirmado para {team}.",
   "match.unreachable": "No se pudo contactar al proveedor de datos \u2014 no se pudo consultar el partido {id}.",
   "team.ambiguous": '"{query}" es ambiguo. \xBFQuisiste decir:',
@@ -517,6 +560,12 @@ var PT = {
   "status.fullTime": "encerrado",
   "status.postponed": "adiado",
   "status.cancelled": "cancelado",
+  "event.goal": "Gol",
+  "event.ownGoal": "Gol contra",
+  "event.penalty": "P\xEAnalti",
+  "event.yellow": "Cart\xE3o amarelo",
+  "event.red": "Cart\xE3o vermelho",
+  "event.sub": "Substitui\xE7\xE3o",
   "live.title": "Ao vivo",
   "today.title": "Jogos de hoje",
   "today.on": "Jogos",
@@ -524,6 +573,17 @@ var PT = {
   "next.label": "Pr\xF3ximo jogo de {team}",
   "next.in": "em {countdown}",
   "countdown.now": "agora",
+  "ambient.syncing": "ao vivo \xB7 sincronizando\u2026",
+  "moment.goal": "GOL!",
+  "moment.ownGoal": "Gol contra",
+  "moment.ownGoalDetail": "gol contra",
+  "moment.goalFor": "Gol \xB7 {team}",
+  "moment.goals": "Gols",
+  "moment.scoreUpdated": "Placar corrigido",
+  "moment.penalties": "P\xEAnaltis",
+  "moment.fullTime": "Fim de jogo",
+  "moment.win": "{team} vence",
+  "moment.draw": "Empate",
   heading: "{title}:",
   "today.none": "Nenhum jogo para esta data.",
   "live.none": "Nenhum jogo em andamento agora.",
@@ -532,6 +592,7 @@ var PT = {
   "feed.earlierRecord": "N\xE3o foi poss\xEDvel atualizar o estado ao vivo \u2014 mostrando o registro anterior do provedor.",
   "next.none": "Nenhum pr\xF3ximo jogo encontrado para {team}.",
   "match.none": "Nenhum jogo encontrado com id {id}.",
+  "match.kickoff": "In\xEDcio",
   "next.unreachable": "N\xE3o foi poss\xEDvel contatar o provedor de dados \u2014 nenhum pr\xF3ximo jogo confirmado para {team}.",
   "match.unreachable": "N\xE3o foi poss\xEDvel contatar o provedor de dados \u2014 o jogo {id} n\xE3o p\xF4de ser consultado.",
   "team.ambiguous": '"{query}" \xE9 amb\xEDguo. Voc\xEA quis dizer:',
@@ -606,6 +667,12 @@ var FR = {
   "status.fullTime": "termin\xE9",
   "status.postponed": "report\xE9",
   "status.cancelled": "annul\xE9",
+  "event.goal": "But",
+  "event.ownGoal": "But contre son camp",
+  "event.penalty": "Penalty",
+  "event.yellow": "Carton jaune",
+  "event.red": "Carton rouge",
+  "event.sub": "Remplacement",
   "live.title": "En direct",
   "today.title": "Matchs d'aujourd'hui",
   "today.on": "Matchs",
@@ -613,6 +680,17 @@ var FR = {
   "next.label": "Prochain match de {team}",
   "next.in": "dans {countdown}",
   "countdown.now": "maintenant",
+  "ambient.syncing": "en direct \xB7 synchronisation\u2026",
+  "moment.goal": "BUT !",
+  "moment.ownGoal": "But contre son camp",
+  "moment.ownGoalDetail": "contre son camp",
+  "moment.goalFor": "But pour {team}",
+  "moment.goals": "Buts",
+  "moment.scoreUpdated": "Score corrig\xE9",
+  "moment.penalties": "Tirs au but",
+  "moment.fullTime": "Fin du match",
+  "moment.win": "{team} gagne",
+  "moment.draw": "Match nul",
   heading: "{title} :",
   "today.none": "Aucun match pr\xE9vu pour cette date.",
   "live.none": "Aucun match en cours pour l'instant.",
@@ -621,6 +699,7 @@ var FR = {
   "feed.earlierRecord": "L\u2019\xE9tat en direct n\u2019a pas pu \xEAtre actualis\xE9 \u2014 affichage de l\u2019enregistrement pr\xE9c\xE9dent du fournisseur.",
   "next.none": "Aucun prochain match trouv\xE9 pour {team}.",
   "match.none": "Aucun match trouv\xE9 avec id {id}.",
+  "match.kickoff": "Coup d\u2019envoi",
   "next.unreachable": "Impossible de joindre le fournisseur de donn\xE9es \u2014 aucun prochain match confirm\xE9 pour {team}.",
   "match.unreachable": "Impossible de joindre le fournisseur de donn\xE9es \u2014 le match {id} n\u2019a pas pu \xEAtre consult\xE9.",
   "team.ambiguous": '"{query}" est ambigu. Vouliez-vous dire :',
@@ -654,6 +733,20 @@ function t(lang, key, vars) {
     (whole, name) => Object.hasOwn(vars, name) ? vars[name] : whole
   );
 }
+function momentWords(lang) {
+  return {
+    goal: t(lang, "moment.goal"),
+    ownGoal: t(lang, "moment.ownGoal"),
+    ownGoalDetail: t(lang, "moment.ownGoalDetail"),
+    goalFor: t(lang, "moment.goalFor"),
+    goals: t(lang, "moment.goals"),
+    scoreUpdated: t(lang, "moment.scoreUpdated"),
+    penalties: t(lang, "moment.penalties"),
+    fullTime: t(lang, "moment.fullTime"),
+    win: t(lang, "moment.win"),
+    draw: t(lang, "moment.draw")
+  };
+}
 var STAGE_KEYS = Object.freeze({
   GROUP: "stage.groupStage",
   R32: "stage.r32",
@@ -842,6 +935,70 @@ function withFlag(text, flag2, side) {
   return side === "home" ? `${flag2} ${text}` : `${text} ${flag2}`;
 }
 
+// src/timeline.ts
+var KIND_KEYS = Object.freeze({
+  GOAL: "event.goal",
+  OWN_GOAL: "event.ownGoal",
+  PEN: "event.penalty",
+  YELLOW: "event.yellow",
+  RED: "event.red",
+  SUB: "event.sub"
+});
+var KIND_MARKS = Object.freeze({
+  GOAL: "\u26BD",
+  OWN_GOAL: "\u26BD",
+  PEN: "\u26BD",
+  YELLOW: "\u{1F7E8}",
+  RED: "\u{1F7E5}",
+  SUB: "\u{1F504}"
+});
+function timelineParts(match, opts) {
+  const events = match.events ?? [];
+  if (events.length === 0) return [];
+  const cells = events.map((e) => {
+    const team = e.side === "home" ? match.home : match.away;
+    return {
+      minute: e.added !== void 0 ? `${e.minute}+${e.added}'` : `${e.minute}'`,
+      mark: KIND_MARKS[e.type],
+      kind: t(opts.lang, KIND_KEYS[e.type]),
+      label: withFlag(team.code, opts.flags ? team.flag : void 0, e.side),
+      player: e.player
+    };
+  });
+  const widest = (pick2) => Math.max(...cells.map((c) => displayWidth(pick2(c))));
+  const minuteW = widest((c) => c.minute);
+  const kindW = widest((c) => c.kind);
+  const labelW = widest((c) => c.label);
+  return cells.map((c) => {
+    const columns = `  ${padVisible(c.minute, minuteW)}  ${c.mark} ${padVisible(c.kind, kindW)}  ${padVisible(c.label, labelW)}`;
+    if (!c.player) return [{ text: columns.trimEnd() }];
+    return [{ text: `${columns}  ` }, { text: c.player, style: "strong" }];
+  });
+}
+function timelineRows(match, opts) {
+  return timelineParts(match, opts).map((row) => row.map((p) => p.text).join(""));
+}
+var SCORING = /* @__PURE__ */ new Set(["GOAL", "OWN_GOAL", "PEN"]);
+function provenLastGoal(match) {
+  const score = match.score;
+  if (!score) return null;
+  let home = 0;
+  let away = 0;
+  let last = null;
+  const identities = /* @__PURE__ */ new Set();
+  for (const e of match.events ?? []) {
+    if (!SCORING.has(e.type)) continue;
+    const identity = JSON.stringify([e.type, e.minute, e.added ?? 0, e.side, e.player ?? null]);
+    if (identities.has(identity)) return null;
+    identities.add(identity);
+    if (e.side === "home") home++;
+    else if (e.side === "away") away++;
+    else continue;
+    last = e;
+  }
+  return last !== null && home === score.home && away === score.away ? last : null;
+}
+
 // src/normalize.ts
 function outcomeFromScore(home, away) {
   if (home > away) return "H";
@@ -1132,18 +1289,33 @@ function sealScorePair(raw) {
   const away = count(v.away, MAX_GOALS);
   return home !== void 0 && away !== void 0 ? { home, away } : void 0;
 }
+var MAX_ADDED_MINUTES = 30;
+var SIDES = /* @__PURE__ */ new Set(["home", "away"]);
 function sealEvent(raw) {
-  if (!raw || typeof raw !== "object") return void 0;
+  if (!raw || typeof raw !== "object") return null;
   const e = raw;
   const type = member(e.type, EVENT_TYPES);
-  if (!type) return void 0;
+  if (!type) return null;
   const minute = count(e.minute, MAX_MINUTE);
-  if (minute === void 0) return void 0;
-  const out = { type, minute, teamCode: humanLabel(e.teamCode, TEAM_CODE_COLUMNS) };
+  if (minute === void 0) return null;
+  let added;
+  if (e.added !== void 0) {
+    added = count(e.added, MAX_ADDED_MINUTES);
+    if (added === void 0 || added < 1) return null;
+  }
+  const side = member(e.side, SIDES);
+  if (!side) return null;
+  const out = { type, minute };
+  if (added !== void 0) out.added = added;
+  out.side = side;
+  out.teamCode = humanLabel(e.teamCode, TEAM_CODE_COLUMNS);
   const player = humanLabel(e.player);
   if (player) out.player = player;
   return out;
 }
+function byClock(a, b) {
+  return a.minute - b.minute || (a.added ?? 0) - (b.added ?? 0);
+}
 function sealMatch(parts, opts = {}) {
   if (!parts || typeof parts !== "object") return malformed("match is not an object");
   const id = opaqueId(parts.id, ESPN_ID);
@@ -1188,7 +1360,8 @@ function sealMatch(parts, opts = {}) {
       winnerCode = claimedWinner;
     }
   }
-  const events = opts.events === false ? [] : takeBounded(parts.events, MAX_MATCH_EVENTS).map(sealEvent).filter((e) => !!e);
+  const timelined = status === "LIVE" || status === "HT" || status === "FT";
+  const events = opts.events === false || !timelined ? [] : takeBounded(parts.events, MAX_MATCH_EVENTS).map(sealEvent).filter((e) => !!e).sort(byClock);
   const out = { id, stage };
   if (stageLabel2) out.stageLabel = stageLabel2;
   if (group) out.group = group;
@@ -4446,6 +4619,75 @@ function parseMinute(st) {
   }
   return void 0;
 }
+var DETAIL_FLAGS = ["scoringPlay", "yellowCard", "redCard", "penaltyKick", "ownGoal", "shootout"];
+var DETAIL_MINUTE = /^(\d{1,3})'$/;
+var DETAIL_MINUTE_ADDED = /^(\d{1,3})'\+(\d{1,2})'$/;
+function detailKind(d) {
+  const f = {};
+  for (const name of DETAIL_FLAGS) {
+    const v = flag(d[name]);
+    if (v === void 0) return void 0;
+    f[name] = v;
+  }
+  if (f.shootout) return void 0;
+  const { scoringPlay: s, yellowCard: y, redCard: r, penaltyKick: p, ownGoal: o } = f;
+  if (s && !y && !r) {
+    if (!p && !o) return "GOAL";
+    if (o && !p) return "OWN_GOAL";
+    if (p && !o) return "PEN";
+    return void 0;
+  }
+  if (p || o || s) return void 0;
+  if (y && !r) return "YELLOW";
+  if (r && !y) return "RED";
+  return void 0;
+}
+function detailMinute(clock) {
+  if (!clock || typeof clock !== "object") return void 0;
+  const dv = clock.displayValue;
+  if (typeof dv !== "string") return void 0;
+  const plain = DETAIL_MINUTE.exec(dv);
+  if (plain) return { minute: Number(plain[1]) };
+  const extra = DETAIL_MINUTE_ADDED.exec(dv);
+  if (!extra) return void 0;
+  return { minute: Number(extra[1]), added: Number(extra[2]) };
+}
+function rawTeamId(holder) {
+  if (!holder || typeof holder !== "object") return void 0;
+  const team = holder.team;
+  if (!team || typeof team !== "object") return void 0;
+  return opaqueId(team.id, ESPN_ID);
+}
+function detailEvents(details, sides) {
+  const out = [];
+  for (const raw of takeBounded(details, MAX_MATCH_EVENTS)) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+    const d = raw;
+    const type = detailKind(d);
+    if (!type) continue;
+    const when = detailMinute(d.clock);
+    if (!when) continue;
+    const teamId = rawTeamId(d);
+    const side = teamId === void 0 ? void 0 : teamId === sides.homeId ? "home" : teamId === sides.awayId ? "away" : void 0;
+    if (!side) continue;
+    const event = { type, minute: when.minute };
+    if (when.added !== void 0) event.added = when.added;
+    event.side = side;
+    event.teamCode = side === "home" ? sides.homeCode : sides.awayCode;
+    const player = detailPlayer(d.athletesInvolved, type === "OWN_GOAL" ? side === "home" ? sides.awayId : sides.homeId : teamId);
+    if (player) event.player = player;
+    out.push(event);
+  }
+  return out;
+}
+function detailPlayer(athletes, expectedTeamId) {
+  if (!Array.isArray(athletes) || athletes.length !== 1 || expectedTeamId === void 0) return void 0;
+  const a = athletes[0];
+  if (rawTeamId(a) !== expectedTeamId) return void 0;
+  const name = a.displayName;
+  if (!isHumanLabel(name)) return void 0;
+  return humanLabel(name) || void 0;
+}
 var MAX_SLUG_UNITS2 = 64;
 var SLUG = /^[a-z0-9-]+$/;
 var EXACT_STAGE = Object.freeze({
@@ -4567,7 +4809,14 @@ function parseEspnEvent(raw, ctx = {}) {
       status,
       winnerCode,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      events: ev.events
+      // The goals and cards: ESPN's `details`, read by the detail grammar; the
+      // seal keeps them only on a status that holds a score.
+      events: detailEvents(comp?.details, {
+        homeId: rawTeamId(homeRaw),
+        awayId: rawTeamId(awayRaw),
+        homeCode: home.code,
+        awayCode: away.code
+      })
     },
     // The final reseal states the same kind the competitors were built with.
     { teamKind: kind }
@@ -4890,7 +5139,7 @@ function fetchMeta(result) {
 // src/adapters/espn.ts
 var ESPN_SOCCER = "https://site.api.espn.com/apis/site/v2/sports/soccer";
 var DEFAULT_COMPETITION = BUNDLED_SLUG;
-var USER_AGENT = `claudinho/${"0.11.2"} (+https://github.com/arturogarrido/claudinho)`;
+var USER_AGENT = `claudinho/${"0.12.0"} (+https://github.com/arturogarrido/claudinho)`;
 var MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 var DEFAULT_COOLDOWN_MS = 5 * 6e4;
 var MAX_COOLDOWN_MS = 15 * 6e4;
@@ -7016,10 +7265,19 @@ async function getScheduleAhead(adapter, now = /* @__PURE__ */ new Date()) {
   };
 }
 async function getLiveMatches(adapter, now = /* @__PURE__ */ new Date()) {
-  const { complete: _complete, ...result } = await getLiveRead(adapter, now);
+  const { complete: _complete, finished: _finished, finishedTruncated: _truncated, ...result } = await getLiveRead(adapter, now);
   return result;
 }
-async function getLiveRead(adapter, now = /* @__PURE__ */ new Date()) {
+var MAX_LIVE_FINISHED = 64;
+function finishedOf(records, seen) {
+  const wanted = new Set(takeBounded(seen, MAX_LIVE_FINISHED));
+  const done = records.filter((m) => m.status === "FT" && m.score !== void 0);
+  const first = done.filter((m) => wanted.has(m.id));
+  const rest = done.filter((m) => !wanted.has(m.id));
+  const all = [...first, ...rest];
+  return { finished: all.slice(0, MAX_LIVE_FINISHED), truncated: all.length > MAX_LIVE_FINISHED };
+}
+async function getLiveRead(adapter, now = /* @__PURE__ */ new Date(), seen = []) {
   try {
     const day = now.toISOString().slice(0, 10);
     const fetched = adapter.fetchWindow ? await adapter.fetchWindow(shiftUtcDate(day, -1), shiftUtcDate(day, 1), { acrossSeasons: true }) : await adapter.fetchLive();
@@ -7027,6 +7285,7 @@ async function getLiveRead(adapter, now = /* @__PURE__ */ new Date()) {
     const season = meta?.season;
     const matches = fetched.filter((m) => isLive(m.status));
     const between = betweenEditionsOf(adapter, meta, fetched, providerDayOf(adapter, now));
+    const done = finishedOf(fetched, seen);
     return {
       matches,
       degraded: false,
@@ -7038,10 +7297,12 @@ async function getLiveRead(adapter, now = /* @__PURE__ */ new Date()) {
       // boolean below is the refresher's, unchanged: false for that, for an
       // adapter that said nothing, and for a failed read alike.
       ...partialOfRead(meta),
-      complete: meta?.complete === true
+      complete: meta?.complete === true,
+      finished: done.finished,
+      finishedTruncated: done.truncated
     };
   } catch {
-    return { matches: [], degraded: true, complete: false };
+    return { matches: [], degraded: true, complete: false, finished: [], finishedTruncated: false };
   }
 }
 
@@ -7291,15 +7552,22 @@ function sealMarketSignal(raw, options = {}) {
   if (sourceMarketId) out.sourceMarketId = sourceMarketId;
   out.asOf = canonicalTimestamp(s.asOf) ?? "";
   out.fetchedAt = canonicalTimestamp(s.fetchedAt) ?? "";
+  const judgedAt = options.now ?? /* @__PURE__ */ new Date();
+  const fetchedMs = Date.parse(out.fetchedAt);
+  if (out.fetchedAt === "" || !Number.isFinite(fetchedMs)) {
+    return malformed("signal carries no readable fetch time");
+  }
+  if (fetchedMs > judgedAt.getTime()) {
+    return unresolved("signal was fetched after the clock it is judged by");
+  }
   out.outcomes = outcomes;
   const isAmbiguous = s.ambiguous !== false;
   const favorite = isAmbiguous ? void 0 : deriveFavorite(outcomes);
   if (favorite) out.favorite = favorite;
   if (liquidity !== void 0) out.liquidity = liquidity;
   if (volume24h !== void 0) out.volume24h = volume24h;
-  out.stale = s.stale !== false;
+  out.stale = isStaleSignal(out, { now: judgedAt, maxAgeMs: options.maxAgeMs });
   out.ambiguous = isAmbiguous || out.source === "";
-  out.stale = out.stale || isStaleSignal(out, { now: options.now, maxAgeMs: options.maxAgeMs });
   return valid(out);
 }
 function parseCachedMarketSignal(raw, options = {}) {
@@ -7308,7 +7576,7 @@ function parseCachedMarketSignal(raw, options = {}) {
 
 // src/markets/normalize.ts
 var DEFAULT_MAX_AGE_MS = 15 * 6e4;
-function marketRelevant(match, now = /* @__PURE__ */ new Date()) {
+function marketRelevant(match, now) {
   if (isLive(match.status)) return true;
   if (isFinished(match.status)) return false;
   const k = Date.parse(match.kickoff);
@@ -7397,12 +7665,13 @@ function buildMarketSignal(input) {
   const outcomes = normalizeOutcomes(input.outcomes);
   const ambiguous2 = input.ambiguous === true || !mapsCleanly(input.match, outcomes);
   const favorite = ambiguous2 ? void 0 : deriveFavorite(outcomes);
+  const clock = input.now ?? /* @__PURE__ */ new Date();
   const signal = {
     matchId: input.match.id,
     source: input.source,
     sourceMarketId: input.sourceMarketId,
     asOf: input.asOf,
-    fetchedAt: input.fetchedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    fetchedAt: input.fetchedAt ?? clock.toISOString(),
     outcomes,
     favorite,
     liquidity: input.liquidity,
@@ -7410,8 +7679,8 @@ function buildMarketSignal(input) {
     stale: false,
     ambiguous: ambiguous2
   };
-  signal.stale = isStaleSignal(signal, { now: input.now, maxAgeMs: input.maxAgeMs });
-  const sealed = sealMarketSignal(signal, { now: input.now, maxAgeMs: input.maxAgeMs });
+  signal.stale = isStaleSignal(signal, { now: clock, maxAgeMs: input.maxAgeMs });
+  const sealed = sealMarketSignal(signal, { now: clock, maxAgeMs: input.maxAgeMs });
   if (sealed.kind !== "valid") {
     return { ...signal, outcomes: [], favorite: void 0, stale: true, ambiguous: true };
   }
@@ -8687,6 +8956,7 @@ export {
   MAX_CONFIG_BYTES,
   MAX_COOLDOWN_MS,
   MAX_LABEL_COLUMNS,
+  MAX_LIVE_FINISHED,
   MAX_RESPONSE_BYTES,
   MAX_SCHEDULE_INDEX,
   NO_BRACKET,
@@ -8836,6 +9106,7 @@ export {
   matchWindowSentence,
   mergeLive,
   modeLine,
+  momentWords,
   nationArg,
   nationToFlag,
   nationToRegion,
@@ -8857,6 +9128,7 @@ export {
   parsedValue,
   pinUnder,
   productFlag,
+  provenLastGoal,
   rallyCryFor,
   rallyEntryFor,
   readJsonBounded,
@@ -8875,6 +9147,7 @@ export {
   scheduleEntryOf,
   scheduleSpan,
   scoreline,
+  sealEvent,
   sealMarketSignal,
   sealMatch,
   sealScheduleEntry,
@@ -8894,7 +9167,10 @@ export {
   tableKeyArg,
   tableShareCard,
   tableTitle,
+  takeBounded,
   teamKind,
+  timelineParts,
+  timelineRows,
   truncateVisible,
   unresolved,
   unservedSentence,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/core",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "The engine behind Claudinho: the domain model, the provider adapters (ESPN), live scores and standings for the competition you follow (16 supported), the bundled 2026 World Cup schedule with its knockout bracket and read-only Polymarket sidecar. Independent fan project. Not affiliated with FIFA, any confederation, league or club, or Anthropic.",
   "type": "module",
   "license": "MIT",
@@ -67,7 +67,7 @@
     "club-world-cup"
   ],
   "devDependencies": {
-    "@types/node": "^22.20.4",
+    "@types/node": "^22.20.5",
     "@vitest/coverage-v8": "^5.0.3",
     "tsup": "^8.0.0",
     "tsx": "^4.23.15",