@claudinho/core 0.11.1 → 0.11.2

package/dist/index.d.ts

@@ -313,16 +313,21 @@ declare function formatDate(iso: string, opts?: FormatOpts): string;
 declare function formatTime(iso: string, opts?: FormatOpts): string;
 /** What {@link countdown} says of a kickoff that has passed (the statusline prints it as it is: English, by its rule). */
 declare const COUNTDOWN_NOW = "now";
-/** Compact human countdown until kickoff: "3d4h", "2h10m", "45m", or {@link COUNTDOWN_NOW}. */
-declare function countdown(iso: string, from?: Date): string;
+/**
+ * Compact human countdown until kickoff: "3d4h", "2h10m", "45m", or {@link COUNTDOWN_NOW}, from `from`: the clock of
+ * the request or render that says it, which every caller hands in (no default: the wall clock is never read here).
+ */
+declare function countdown(iso: string, from: Date): string;
 /**
  * The countdown as the reader's phrase, ONE rule for every localized line that
  * says it (CLI `next`, the MCP match line): "in 3d4h" (`next.in`), or, for a
  * kickoff that has passed (a stale record, the bundle's skeleton during an
  * outage), the language's own word for now (`countdown.now`), never the
- * English word inside a translated "in".
+ * English word inside a translated "in". Relative to the REQUEST's clock
+ * (`from`), the one every other read of the request takes and every caller
+ * passes: the wall clock is never read here.
  */
-declare function countdownPhrase(lang: string | undefined, iso: string, from?: Date): string;
+declare function countdownPhrase(lang: string | undefined, iso: string, from: Date): string;
 /**
  * The calendar date (YYYY-MM-DD) of a kickoff in the target timezone, or ''
  * when the input can't be parsed — an unfileable fixture matches no date rather
@@ -1384,6 +1389,15 @@ interface LiveResult {
      */
     served?: readonly string[];
 }
+/**
+ * THE clock of a request: the one its caller gave (a test's, a command's
+ * context), else the adapter's read clock ({@link clockOf}: the clock the
+ * adapter's reads and its cooldown count by, the wall clock in production).
+ * A surface reads it ONCE per request, after resolving its adapter, and hands
+ * it to every read and every rendering of the request, so a lookup and a
+ * countdown in one answer agree on "now".
+ */
+declare function requestClock(adapter: ProviderAdapter, given?: Date): Date;
 /** Human label for a live-data provider name (attribution). Text only. */
 declare function liveSourceLabel(source: string): string;
 /**
@@ -3054,6 +3068,314 @@ declare const FAN_PROJECT = "Independent fan project";
  */
 declare function disclaimerLine(host?: string): string;
 
+/**
+ * Where a selection came from: the command line's `--competition` or a tool's
+ * `competition` argument (`flag`), `CLAUDINHO_COMPETITION` (`env`), or the
+ * user's saved choice (`saved`: the config file `claudinho follow` writes).
+ * Nothing else chooses: with none of the three there is no competition
+ * (`{ kind: 'none' }`), never a default.
+ */
+type ChosenBy = 'flag' | 'env' | 'saved';
+/** A competition a request is for, and where that choice came from. */
+interface SelectedCompetition {
+    readonly kind: 'selected';
+    /** The provider's slug the request asks for. */
+    readonly slug: string;
+    /** The table's alias; absent for a raw slug. */
+    readonly alias?: string;
+    /** What a surface names it: the table's name, or a raw slug as it is. */
+    readonly name: string;
+    readonly chosenBy: ChosenBy;
+    /** A raw slug the table does not hold: the escape hatch, labelled. */
+    readonly experimental: boolean;
+}
+/**
+ * What the edge resolved: a competition; a value that is neither an alias nor
+ * a slug, REFUSED with the aliases (an unknown value is never a request); or
+ * `none`: nothing was chosen (no flag, no environment, no saved choice). The
+ * finished World Cup is not a default anyone falls into without choosing.
+ */
+type CompetitionSelection = SelectedCompetition | {
+    readonly kind: 'refused';
+    readonly value: string;
+    readonly aliases: string[];
+    /** The source that gave the refused value (a flag or the environment: the file's reader refuses its own). */
+    readonly chosenBy: ChosenBy;
+} | {
+    readonly kind: 'none';
+};
+/**
+ * The ONE constructor of a selected competition: a slug and where it was
+ * chosen, described by the table (its alias and name) or, for a slug the
+ * table does not hold, as itself and experimental. The resolver builds every
+ * selection through it; an edge that already holds a slug (a config built
+ * without the resolver) describes it through it too, never by hand.
+ */
+declare function selectedCompetition(slug: string, chosenBy: ChosenBy): SelectedCompetition;
+/**
+ * THE EDGE. The one function that decides which competition a request is for,
+ * from the values its edge hands in: the flag (`--competition`, a tool's
+ * `competition` argument), then the environment (`CLAUDINHO_COMPETITION`), then
+ * the saved choice (the config file's `competition`, read at the edge through
+ * core's one reader: `readUserConfig`). The FIRST present source decides (an
+ * empty string is absent): a present value that is refused is refused, even
+ * when a lower source holds a valid one (what was asked for is not answered
+ * with something else). With no source present, `none`: nothing is chosen,
+ * and every competition-answering surface says so instead of answering.
+ *
+ * Each value is an alias (`premier-league`), a slug in the table (`eng.1`), or
+ * a raw ESPN slug the table does not hold (`fifa.friendly`, `esp.copa_del_rey`:
+ * lower-case segments of letters, digits and underscores joined by dots, 64
+ * units at most; experimental);
+ * anything else (`foo`, `ENG.1`, a space) is refused with the aliases.
+ *
+ * Core reads NO environment and no file: the edges pass them. It is called
+ * where a request ENTERS (the CLI's option resolution, the MCP server's
+ * request) and nowhere else. From there the competition travels as a value
+ * (on the config, on the adapter), so nothing further down can answer for a
+ * different competition halfway through. `core/test/selection-identity.test.ts`
+ * fails if a call appears anywhere else.
+ */
+declare function resolveCompetition(explicit?: string, env?: string, saved?: string): CompetitionSelection;
+/**
+ * The line every competition-answering text answer prints after its header:
+ * the competition's name, then where the choice came from when it was the
+ * flag or the environment (`from the command line`; on MCP, `from the
+ * request`; `from the environment`), then `experimental` for a raw slug. A
+ * saved choice prints the name alone. The name is not localized; the rest is.
+ * Empty for a selection that is not a competition.
+ */
+declare function modeLine(selection: CompetitionSelection, lang?: string, 
+/** What a flag is on this surface: the command line's, or a tool request's argument. */
+flag?: 'command' | 'request'): string;
+/** The structured form of a selection: what `--json` and MCP `data` carry. */
+interface CompetitionKey {
+    readonly slug: string;
+    readonly alias?: string;
+    readonly name: string;
+    readonly chosenBy: ChosenBy;
+    readonly experimental?: true;
+}
+/**
+ * The selection as ONE structured key, `competition`, for every
+ * competition-answering structured answer (CLI `--json`, MCP `data`): the
+ * alias only when there is one, `experimental` only when true; `null` when
+ * nothing is chosen (beside the `noCompetition` verdict: see
+ * {@link selectionVerdict}). Nothing for a refused value (it is an error, never
+ * an answer). Every emit site spreads this; none builds the key by hand.
+ */
+declare function selectionExtras(selection: CompetitionSelection): {
+    competition?: CompetitionKey | null;
+};
+/**
+ * The verdict a selection states about every answer made under it: with
+ * nothing chosen, `noCompetition` (the first replacing verdict: its sentence
+ * stands instead of any answer, and its key goes beside `competition: null`);
+ * nothing otherwise. A surface hands THIS to `verdictNotice`/`verdictExtras`,
+ * never an object it builds itself.
+ */
+declare function selectionVerdict(selection: CompetitionSelection): VerdictSource;
+/**
+ * Why a selection is not a competition, in the reader's language; undefined
+ * for a competition. A refused value names the value (bounded) and the
+ * aliases; nothing chosen is the CLI's sentence (`claudinho follow <alias>`,
+ * `follow --list`): MCP answers nothing chosen with the `noCompetition`
+ * verdict's own sentence (`verdictNotice`), never this one. The CLI raises it
+ * as an input error, MCP a refused value as a tool error, before any request.
+ */
+declare function selectionRefusal(selection: CompetitionSelection, lang?: string): string | undefined;
+/** The competition whose schedule ships bundled in the clients: the World Cup. */
+declare const BUNDLE_COMPETITION = "fifa.world";
+/**
+ * The edition the bundled schedule describes, read from the schedule itself
+ * (the year of its first kickoff) rather than written down a second time.
+ */
+declare function bundleSeasonYear(): number;
+/**
+ * Does the bundled schedule describe what this request is about?
+ *
+ * The competition is an ARGUMENT — the caller's adapter states it — never a
+ * default. Off the bundle, every path built on the skeleton (date merge,
+ * `match <id>`, `next`, the bracket, the knockout-fixture cache, the market
+ * fixture) must not read it: an empty foreign day once showed 104 World Cup
+ * fixtures with foreign attribution (audit A03).
+ *
+ * The bundle is ONE EDITION of its competition. When the provider reported the
+ * season a response belongs to and it is a different one, the bundle does not
+ * describe that response. With no provider answer (offline, degraded) there is
+ * nothing to compare, and the bundle stays what it is: the 2026 edition.
+ */
+declare function bundleApplies(competition: string, season?: SeasonInfo): boolean;
+/**
+ * The competitions that HAVE NO BRACKET: league seasons with no knockout tie of
+ * their own, where "no bracket" is the answer, not a gap. Written down in the
+ * supported table (`bracket: 'not-applicable'`), one fact each, never inferred
+ * from the standings shape (`STANDINGS_SHAPE` says
+ * how a table is read, not whether a knockout follows it: `uefa.champions` and
+ * `mex.1` read as one league table and both have one).
+ *   - `eng.1`: the Premier League; a 38-round league, no play-off.
+ *   - `esp.1`: LaLiga; a 38-round league, no play-off.
+ * Deliberately NOT here: `ita.1` (championship and relegation play-offs since
+ * the FIGC's May 2026 decision), `ger.1` (the relegation play-off), `mex.1`
+ * (the Liguilla), `uefa.champions` (a knockout after the league phase). A
+ * competition joins by a written fact. A derived view, kept for its readers (it
+ * is exported); {@link bracketCapability} reads the row itself.
+ */
+declare const NO_BRACKET: ReadonlySet<string>;
+/**
+ * What `bracket` is for a competition, one of three values, read from its ROW
+ * (one row, one fact: a listing, the README matrix and the command cannot
+ * disagree):
+ *   - `offered`: the row offers it (only the bundled competition can:
+ *     `deriveTables` refuses any other row that does);
+ *   - `inapplicable`: the row says the competition has none (`not-applicable`);
+ *   - `unsupported`: it may have one, and it is not offered yet; also a slug
+ *     the table does not hold.
+ */
+declare function bracketCapability(competition: string, table?: readonly CompetitionEntry[]): 'offered' | 'inapplicable' | 'unsupported';
+
+/**
+ * The ambient view: what `claudinho ambient --json` prints, ONE JSON object on
+ * one line, for a program that shows the statusline and the hook itself (the
+ * Claude Code plugin's band, its toasts and its prompt context). A type and
+ * its documentation only: the CLI builds it from its local cache (the
+ * statusline's reader, in `packages/cli`), and core reads no cache and no
+ * environment for it.
+ *
+ * Three shapes reach a reader, and the command always exits 0:
+ *   - nothing chosen (no `--competition`, no `CLAUDINHO_COMPETITION`, no saved
+ *     choice): the selection's structured twin, `competition: null` beside the
+ *     verdict that says nothing is chosen, and `line` (the statusline's
+ *     first-run line); no cache is read and no refresher started;
+ *   - a value that is no competition, or a failure anywhere: `line` (the
+ *     statusline's empty line) and `empty: true` alone, no view;
+ *   - a selected competition: an {@link AmbientView}.
+ */
+
+/**
+ * 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:
+ */
+type AmbientMatch = Match & {
+    /**
+     * A side of it is the ambient PREFERENCE's (`pick`): `CLAUDINHO_TEAM`'s
+     * code, else the saved pin. The picked matches come first in the list.
+     */
+    readonly picked: boolean;
+    /**
+     * A side of it is the SAVED pin's (`claudinho follow <alias> --team`), by
+     * the pin's id when it has one (a club), by its code when it has none (the
+     * World Cup's nations); whatever `CLAUDINHO_TEAM` prefers.
+     */
+    readonly pinned: boolean;
+    /**
+     * 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
+     * where flags are on and the side has one, the scoreline with a shootout's
+     * tally, the minute token: `67'`, `half-time`, `live`). A program says it,
+     * never composes one.
+     */
+    readonly line: string;
+};
+/** 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.
+     */
+    readonly line: string;
+    /**
+     * 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
+     * user follows another competition, so a program reads it slowly. Said of
+     * the line before any fit: a program reads the pace from this, never from the
+     * text, which `--columns` may have cut.
+     */
+    readonly idle: boolean;
+    /**
+     * The line says nothing is known (`⚽ —`): no live match read, no window to
+     * sync in, nothing to count down to. A program shows nothing for it. Said
+     * of the line before any fit: a program reads the visibility from this,
+     * never from the text.
+     */
+    readonly empty: boolean;
+    /** The hook's block, as `claudinho hook` prints it while a match is live; `null` when it prints nothing. */
+    readonly context: string | null;
+    /**
+     * The live matches the statusline reads (a believed snapshot's, inside the
+     * display window), the preference's first. `complete` says the scan was
+     * whole and `total` is exact only then; an empty list with `complete: false`
+     * is "not known". An empty list is "nothing on" ONLY beside `current: true`:
+     * with `current: false` (no snapshot, a stale one, a stamp the reader does
+     * not believe, a degraded one, one whose read was not whole or that does
+     * not say, the syncing window) it says nothing about
+     * play, a match may be on (`line` is the authority: it prints
+     * `live · syncing…` in the window), and a program must never read
+     * `complete && items.length === 0` alone as "nothing on". A degraded
+     * snapshot (the last read failed) may still carry a live record: it is
+     * listed, best effort, as the line shows it, and is never current.
+     */
+    readonly live: BoundedList<AmbientMatch>;
+    /**
+     * 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),
+     * the snapshot is not degraded (a degraded one means the fetch failed, not
+     * that the feed said nothing: it is never current, whatever it carries), the
+     * snapshot states that the read that filled its live slice was whole (a read
+     * that was not, an unreadable record left out beside readable ones, is never
+     * current; nor is a snapshot that does not say, written before 0.11.2, until
+     * one refresh cycle rewrites it), and the line is not syncing: then, and
+     * only then, an empty list means the feed said nothing is in play.
+     */
+    readonly current: boolean;
+    /**
+     * 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.
+     */
+    readonly next: Match | null;
+    /**
+     * The ambient preference as the CLI holds it: `{ code }` from
+     * `CLAUDINHO_TEAM`, the saved pin (`{ id?, code, name }`) when that is
+     * unset, or `null`.
+     */
+    readonly pick: {
+        readonly code: string;
+    } | Pin | null;
+    /**
+     * Present (and `true`) when `CLAUDINHO_TEAM` is set to a value the hot path
+     * cannot read offline (off the World Cup, anything but a three-letter code;
+     * on it, a name its roster does not hold): `pick` is then `null`, never the
+     * pin (the environment is the override).
+     */
+    readonly pickUnreadable?: true;
+    /** The selection, as every `--json` answer carries it (core `selectionExtras`). */
+    readonly competition: CompetitionKey;
+    /** 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. */
+    readonly source: string | null;
+    /**
+     * When the snapshot was written (ISO 8601, re-emitted canonically), or
+     * `null` with no snapshot or a stamp the reader does not believe (further in
+     * the future than its clock-skew allowance: its live scores are not shown).
+     */
+    readonly updatedAt: string | null;
+    /**
+     * When the snapshot's live scores stop being shown (`updatedAt` plus the
+     * statusline's display window), or `null` whenever `updatedAt` is.
+     */
+    readonly staleAfter: string | null;
+    /** The non-affiliation sentence, core's `DISCLAIMER`. */
+    readonly disclaimer: string;
+}
+
 /** The two v1 snippet shapes. `social` is the rich card; `compact` is one terse line per match. */
 type ShareStyle = 'compact' | 'social';
 /** The project social tag — a distribution unit, default-on but removable. */
@@ -3544,172 +3866,6 @@ declare function isPlaceholderSide(team: Pick<Team, 'flag'>): boolean;
 /** The bundled knockout bracket topology (generated by gen:schedule). */
 declare function loadBracketTopology(): BracketTopology;
 
-/**
- * Where a selection came from: the command line's `--competition` or a tool's
- * `competition` argument (`flag`), `CLAUDINHO_COMPETITION` (`env`), or the
- * user's saved choice (`saved`: the config file `claudinho follow` writes).
- * Nothing else chooses: with none of the three there is no competition
- * (`{ kind: 'none' }`), never a default.
- */
-type ChosenBy = 'flag' | 'env' | 'saved';
-/** A competition a request is for, and where that choice came from. */
-interface SelectedCompetition {
-    readonly kind: 'selected';
-    /** The provider's slug the request asks for. */
-    readonly slug: string;
-    /** The table's alias; absent for a raw slug. */
-    readonly alias?: string;
-    /** What a surface names it: the table's name, or a raw slug as it is. */
-    readonly name: string;
-    readonly chosenBy: ChosenBy;
-    /** A raw slug the table does not hold: the escape hatch, labelled. */
-    readonly experimental: boolean;
-}
-/**
- * What the edge resolved: a competition; a value that is neither an alias nor
- * a slug, REFUSED with the aliases (an unknown value is never a request); or
- * `none`: nothing was chosen (no flag, no environment, no saved choice). The
- * finished World Cup is not a default anyone falls into without choosing.
- */
-type CompetitionSelection = SelectedCompetition | {
-    readonly kind: 'refused';
-    readonly value: string;
-    readonly aliases: string[];
-    /** The source that gave the refused value (a flag or the environment: the file's reader refuses its own). */
-    readonly chosenBy: ChosenBy;
-} | {
-    readonly kind: 'none';
-};
-/**
- * The ONE constructor of a selected competition: a slug and where it was
- * chosen, described by the table (its alias and name) or, for a slug the
- * table does not hold, as itself and experimental. The resolver builds every
- * selection through it; an edge that already holds a slug (a config built
- * without the resolver) describes it through it too, never by hand.
- */
-declare function selectedCompetition(slug: string, chosenBy: ChosenBy): SelectedCompetition;
-/**
- * THE EDGE. The one function that decides which competition a request is for,
- * from the values its edge hands in: the flag (`--competition`, a tool's
- * `competition` argument), then the environment (`CLAUDINHO_COMPETITION`), then
- * the saved choice (the config file's `competition`, read at the edge through
- * core's one reader: `readUserConfig`). The FIRST present source decides (an
- * empty string is absent): a present value that is refused is refused, even
- * when a lower source holds a valid one (what was asked for is not answered
- * with something else). With no source present, `none`: nothing is chosen,
- * and every competition-answering surface says so instead of answering.
- *
- * Each value is an alias (`premier-league`), a slug in the table (`eng.1`), or
- * a raw ESPN slug the table does not hold (`fifa.friendly`, `esp.copa_del_rey`:
- * lower-case segments of letters, digits and underscores joined by dots, 64
- * units at most; experimental);
- * anything else (`foo`, `ENG.1`, a space) is refused with the aliases.
- *
- * Core reads NO environment and no file: the edges pass them. It is called
- * where a request ENTERS (the CLI's option resolution, the MCP server's
- * request) and nowhere else. From there the competition travels as a value
- * (on the config, on the adapter), so nothing further down can answer for a
- * different competition halfway through. `core/test/selection-identity.test.ts`
- * fails if a call appears anywhere else.
- */
-declare function resolveCompetition(explicit?: string, env?: string, saved?: string): CompetitionSelection;
-/**
- * The line every competition-answering text answer prints after its header:
- * the competition's name, then where the choice came from when it was the
- * flag or the environment (`from the command line`; on MCP, `from the
- * request`; `from the environment`), then `experimental` for a raw slug. A
- * saved choice prints the name alone. The name is not localized; the rest is.
- * Empty for a selection that is not a competition.
- */
-declare function modeLine(selection: CompetitionSelection, lang?: string, 
-/** What a flag is on this surface: the command line's, or a tool request's argument. */
-flag?: 'command' | 'request'): string;
-/** The structured form of a selection: what `--json` and MCP `data` carry. */
-interface CompetitionKey {
-    readonly slug: string;
-    readonly alias?: string;
-    readonly name: string;
-    readonly chosenBy: ChosenBy;
-    readonly experimental?: true;
-}
-/**
- * The selection as ONE structured key, `competition`, for every
- * competition-answering structured answer (CLI `--json`, MCP `data`): the
- * alias only when there is one, `experimental` only when true; `null` when
- * nothing is chosen (beside the `noCompetition` verdict: see
- * {@link selectionVerdict}). Nothing for a refused value (it is an error, never
- * an answer). Every emit site spreads this; none builds the key by hand.
- */
-declare function selectionExtras(selection: CompetitionSelection): {
-    competition?: CompetitionKey | null;
-};
-/**
- * The verdict a selection states about every answer made under it: with
- * nothing chosen, `noCompetition` (the first replacing verdict: its sentence
- * stands instead of any answer, and its key goes beside `competition: null`);
- * nothing otherwise. A surface hands THIS to `verdictNotice`/`verdictExtras`,
- * never an object it builds itself.
- */
-declare function selectionVerdict(selection: CompetitionSelection): VerdictSource;
-/**
- * Why a selection is not a competition, in the reader's language; undefined
- * for a competition. A refused value names the value (bounded) and the
- * aliases; nothing chosen is the CLI's sentence (`claudinho follow <alias>`,
- * `follow --list`): MCP answers nothing chosen with the `noCompetition`
- * verdict's own sentence (`verdictNotice`), never this one. The CLI raises it
- * as an input error, MCP a refused value as a tool error, before any request.
- */
-declare function selectionRefusal(selection: CompetitionSelection, lang?: string): string | undefined;
-/** The competition whose schedule ships bundled in the clients: the World Cup. */
-declare const BUNDLE_COMPETITION = "fifa.world";
-/**
- * The edition the bundled schedule describes, read from the schedule itself
- * (the year of its first kickoff) rather than written down a second time.
- */
-declare function bundleSeasonYear(): number;
-/**
- * Does the bundled schedule describe what this request is about?
- *
- * The competition is an ARGUMENT — the caller's adapter states it — never a
- * default. Off the bundle, every path built on the skeleton (date merge,
- * `match <id>`, `next`, the bracket, the knockout-fixture cache, the market
- * fixture) must not read it: an empty foreign day once showed 104 World Cup
- * fixtures with foreign attribution (audit A03).
- *
- * The bundle is ONE EDITION of its competition. When the provider reported the
- * season a response belongs to and it is a different one, the bundle does not
- * describe that response. With no provider answer (offline, degraded) there is
- * nothing to compare, and the bundle stays what it is: the 2026 edition.
- */
-declare function bundleApplies(competition: string, season?: SeasonInfo): boolean;
-/**
- * The competitions that HAVE NO BRACKET: league seasons with no knockout tie of
- * their own, where "no bracket" is the answer, not a gap. Written down in the
- * supported table (`bracket: 'not-applicable'`), one fact each, never inferred
- * from the standings shape (`STANDINGS_SHAPE` says
- * how a table is read, not whether a knockout follows it: `uefa.champions` and
- * `mex.1` read as one league table and both have one).
- *   - `eng.1`: the Premier League; a 38-round league, no play-off.
- *   - `esp.1`: LaLiga; a 38-round league, no play-off.
- * Deliberately NOT here: `ita.1` (championship and relegation play-offs since
- * the FIGC's May 2026 decision), `ger.1` (the relegation play-off), `mex.1`
- * (the Liguilla), `uefa.champions` (a knockout after the league phase). A
- * competition joins by a written fact. A derived view, kept for its readers (it
- * is exported); {@link bracketCapability} reads the row itself.
- */
-declare const NO_BRACKET: ReadonlySet<string>;
-/**
- * What `bracket` is for a competition, one of three values, read from its ROW
- * (one row, one fact: a listing, the README matrix and the command cannot
- * disagree):
- *   - `offered`: the row offers it (only the bundled competition can:
- *     `deriveTables` refuses any other row that does);
- *   - `inapplicable`: the row says the competition has none (`not-applicable`);
- *   - `unsupported`: it may have one, and it is not offered yet; also a slug
- *     the table does not hold.
- */
-declare function bracketCapability(competition: string, table?: readonly CompetitionEntry[]): 'offered' | 'inapplicable' | 'unsupported';
-
 /**
  * Metadata that belongs to ONE fetch result.
  *
@@ -3911,4 +4067,4 @@ declare function lookAtEntry(path: string): FileEntry;
  */
 declare function lookAtOwnFile(path: string, maxBytes: number): OwnFile;
 
-export { 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, 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 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 };

package/dist/index.js

@@ -763,7 +763,7 @@ function formatTime(iso, opts = {}) {
   }).format(when);
 }
 var COUNTDOWN_NOW = "now";
-function countdown(iso, from = /* @__PURE__ */ new Date()) {
+function countdown(iso, from) {
   const when = parsedDate(iso);
   if (!when) return UNKNOWN_TIME;
   const ms = when.getTime() - from.getTime();
@@ -776,7 +776,7 @@ function countdown(iso, from = /* @__PURE__ */ new Date()) {
   if (hours > 0) return `${hours}h${mins}m`;
   return `${mins}m`;
 }
-function countdownPhrase(lang, iso, from = /* @__PURE__ */ new Date()) {
+function countdownPhrase(lang, iso, from) {
   const left = countdown(iso, from);
   return left === COUNTDOWN_NOW ? t(lang, "countdown.now") : t(lang, "next.in", { countdown: left });
 }
@@ -4890,7 +4890,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.1"} (+https://github.com/arturogarrido/claudinho)`;
+var USER_AGENT = `claudinho/${"0.11.2"} (+https://github.com/arturogarrido/claudinho)`;
 var MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 var DEFAULT_COOLDOWN_MS = 5 * 6e4;
 var MAX_COOLDOWN_MS = 15 * 6e4;
@@ -6606,6 +6606,9 @@ function mergeLive(base, live) {
 function clockOf(adapter) {
   return new Date(adapter.now?.() ?? Date.now());
 }
+function requestClock(adapter, given) {
+  return given ?? clockOf(adapter);
+}
 function providerDayOf(adapter, instant) {
   if (Number.isNaN(instant.getTime())) return "";
   return adapter.bucketDay?.(instant) || instant.toISOString().slice(0, 10);
@@ -6780,7 +6783,7 @@ async function marketFixtureForTeam(adapter, code, now = /* @__PURE__ */ new Dat
   });
   let refreshRead = {};
   if (candidate) {
-    const { partial, served: _served, ...r } = await getMatchById(adapter, candidate.id);
+    const { partial, served: _served, ...r } = await getMatchById(adapter, candidate.id, now);
     refreshRead = partial ? { partial } : {};
     const m = r.degraded ? candidate : r.match ?? candidate;
     if (!isFinished(m.status)) return { ...r, match: m, ...bothReads(windowRead, refreshRead) };
@@ -8859,6 +8862,7 @@ export {
   readJsonBounded,
   readSmallFile,
   readUserConfig,
+  requestClock,
   resolveClub,
   resolveCompetition,
   resolveMarketSource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudinho/core",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "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",