courthive-components 6.0.1 → 6.2.0

package/dist/components/matchUpFormat/matchUpFormatLogic.d.ts

@@ -11,7 +11,7 @@ export declare const MATCH_ROOTS: readonly ["SET", "HAL", "QTR", "PER", "INN", "
 export declare const MATCH_ROOT_LABELS: Record<string, string>;
 /**
  * Returns valid bestOf options for a given match root.
- * SET root: [1,3,5] (standard tennis)
+ * SET root: [1,3,5,7,9] — odd counts; the factory parses any best-of count (#5136)
  * Other roots: [1..12] (wide range for cross-sport)
  */
 export declare function getBestOfOptionsForRoot(matchRoot?: string): number[];

package/dist/components/schedule-page/domain/utils.d.ts

@@ -1,5 +1,25 @@
-import { CatalogMatchUpItem, MatchUpSide } from '../types';
+import { CatalogMatchUpItem, MatchUpSide, ScheduleCellSide } from '../types';
 export declare function deepClone<T>(obj: T): T;
 export declare function matchUpLabel(item: CatalogMatchUpItem): string;
 export declare function participantLabel(side?: MatchUpSide): string;
+/**
+ * Everything a catalog item can be found by, as one lower-cased line.
+ *
+ * `sides[].participantName` alone left doubles players unfindable by their own
+ * name: the factory composes a PAIR's `participantName` from family names only
+ * (`Phoebus/Smith`), so a search for "Aiden Phoebus" matched his singles matchUps
+ * and silently skipped every doubles matchUp he was in. `individualParticipants`
+ * carries the given+family names that the pair name drops, so both are pushed.
+ */
+/**
+ * "Aiden Phoebus / Ravi Smith" — a doubles side's members, spelled out in full.
+ *
+ * Empty for a singles side and for an un-hydrated pair, which is the caller's cue to
+ * set no tooltip at all rather than an empty one.
+ *
+ * Pure and here rather than inline in the renderer so it can be tested without a DOM:
+ * the ecosystem's DOM layer is Playwright/Storybook, and `test-storybook` cannot
+ * currently run in this repo (612/612 suites fail in the runner, measured 2026-09-27).
+ */
+export declare function memberNamesLabel(side?: MatchUpSide | ScheduleCellSide): string;
 export declare function matchUpSearchKey(item: CatalogMatchUpItem): string;

package/dist/components/schedule-page/index.d.ts

@@ -9,7 +9,7 @@ export { SchedulePageControl } from './controller/schedulePageControl';
 export { SchedulePageStore } from './engine/schedulePageStore';
 export { filterMatchUpCatalog, groupMatchUpCatalog, computeBaseRoundByEvent, isCompletedStatus } from './domain/matchUpCatalogProjections';
 export { buildScheduleIssueIndex } from './domain/scheduleIssues';
-export { matchUpLabel, participantLabel, matchUpSearchKey, deepClone } from './domain/utils';
+export { matchUpLabel, participantLabel, matchUpSearchKey, memberNamesLabel, deepClone } from './domain/utils';
 export { computeActiveStrip, computeActiveStripCell, computeActiveStripDropTarget, computeReschedulePlacements } from './domain/activeStrip';
 export type { ActiveStripCell, ActiveStripCellState, ActiveStripCourtColumn, ActiveStripDropCandidate, ActiveStripDropTarget, ActiveStripGrid, ActiveStripGridMatchUp, ActiveStripStatusOptions, RescheduleCandidate, ReschedulePlacement } from './domain/activeStrip';
 export { buildScheduleDateStrip } from './ui/dateStrip';

package/dist/components/schedule-page/types.d.ts

@@ -9,6 +9,19 @@ export interface MatchUpSide {
     participantId?: string;
     seedNumber?: number;
     ranking?: number;
+    /**
+     * Hydrated members of a pair or team, present on `inContext` matchUps.
+     *
+     * Load-bearing for search, not for layout. A PAIR participant's own
+     * `participantName` is composed by the factory from FAMILY NAMES ALONE
+     * (`Phoebus/Smith`), so a doubles side carries no given name anywhere — and a
+     * consumer searching for "Aiden Phoebus" could not match the one cell he is
+     * actually in. These are the names that make him findable.
+     */
+    individualParticipants?: {
+        participantId?: string;
+        participantName?: string;
+    }[];
 }
 export interface CatalogMatchUpItem {
     matchUpId: string;
@@ -238,6 +251,19 @@ export interface ScheduleCellSide {
     teamName?: string;
     /** True if this side is a BYE (no participant) */
     bye?: boolean;
+    /**
+     * Hydrated members of a pair or team, present on `inContext` matchUps.
+     *
+     * Load-bearing for search, not for layout. A PAIR participant's own
+     * `participantName` is composed by the factory from FAMILY NAMES ALONE
+     * (`Phoebus/Smith`), so a doubles side carries no given name anywhere — and a
+     * consumer searching for "Aiden Phoebus" could not match the one cell he is
+     * actually in. These are the names that make him findable.
+     */
+    individualParticipants?: {
+        participantId?: string;
+        participantName?: string;
+    }[];
 }
 /**
  * Flat data shape the cell renderer consumes — mapped from factory matchUp objects.

package/dist/components/scoring/approaches/dialPadLogic.d.ts

@@ -10,3 +10,8 @@ export type FormatOptions = {
  * Example: "6464" with matchUpFormat 'SET3-S:6/TB7' becomes "6-4 6-4"
  */
 export declare function formatScoreString(digits: string, options: FormatOptions): string;
+/**
+ * The number of sets a format names. `matchUpFormatCode.parse` puts `bestOf` and `exactly` at the top level
+ * of the parsed format, never inside `setFormat`.
+ */
+export declare function setCountOf(parsedFormat: any): number;

package/dist/components/scoring/keyboard.d.ts

@@ -0,0 +1,24 @@
+import { SideNumber } from './logic/scoreEntryState';
+/**
+ * The LOWER participant's row — where entry begins, in every approach.
+ *
+ * CA, 2026-09-28: *"the dynamic sets when launched should always initially give focus to the lower
+ * row; that way e.g. 3 is lower row and shift+3 is upper row, which feels natural ... each subsequent
+ * entry column should start on the bottom cell."*
+ *
+ * Named rather than written as a bare `2` at each site: it is one decision, and the shifted case is
+ * derived from it (`otherSide`) so the two can never be set independently and disagree.
+ */
+export declare const ENTRY_SIDE: SideNumber;
+/** The side a SHIFTED keystroke writes to — the upper row, by construction. */
+export declare const SHIFTED_SIDE: SideNumber;
+export declare function otherSide(sideNumber: SideNumber): SideNumber;
+/**
+ * The digit a key press means, or `undefined` for anything that is not a digit key.
+ *
+ * Both the number row and the numpad, because an operator entering scores at speed uses whichever is
+ * under their hand.
+ */
+export declare function digitFromCode(code: string): number | undefined;
+/** Whether a key event carries a modifier that means it belongs to the browser or the OS. */
+export declare function hasCommandModifier(event: KeyboardEvent): boolean;

package/dist/components/scoring/logic/dynamicSetsLogic.d.ts

@@ -1,17 +1,37 @@
 import { SetScore } from '../types';
 /**
  * Set format information returned by matchUpFormatCode.parse()
+ *
+ * ── `NoAD`, and why the casing is load-bearing ──
+ *
+ * This type is a hand-written MIRROR of what `matchUpFormatCode.parse` emits, and it named the
+ * no-advantage flag `noAd` while the factory emits **`NoAD`**. Measured 2026-09-28:
+ * `parse('SET1-S:TB10NOAD').setFormat.tiebreakSet` is `{ tiebreakTo: 10, NoAD: true }`, so every read
+ * of `.noAd` in this module answered `undefined` for every format — and the TYPE is what made those
+ * reads look correct.
+ *
+ * Nothing threw and nothing logged; no-advantage scoring was simply ignored. Two measured
+ * consequences, both live in the shipping dialog: a low of 6 in a `TB7NOAD` completed to **8** instead
+ * of 7, and a low of 5 in `S:6NOAD` completed to **7** instead of 6 — a 7-5 in a format where first to
+ * six wins.
+ *
+ * Every OTHER reader of this flag in the package had it right — `freeScore.ts`, `matchUpFormat.ts`,
+ * `matchUpFormatLogic.ts` and the format picker all read `.NoAD`. This one type was the outlier, which
+ * is the shape the architectural standards call mock divergence: a hand-written mirror that renames a
+ * field and then certifies the rename.
  */
 export type SetFormat = {
     setTo?: number;
     tiebreakAt?: number;
+    /** No-advantage on the SET — with no tiebreak, the set ends at `setTo` without a two-game margin. */
+    NoAD?: boolean;
     tiebreakFormat?: {
         tiebreakTo?: number;
-        noAd?: boolean;
+        NoAD?: boolean;
     };
     tiebreakSet?: {
         tiebreakTo?: number;
-        noAd?: boolean;
+        NoAD?: boolean;
     };
     timed?: boolean;
     minutes?: number;
@@ -25,6 +45,7 @@ export type SetFormat = {
 export type MatchUpConfig = {
     bestOf: number;
     exactly?: number;
+    aggregate?: boolean;
     setFormat?: SetFormat;
     finalSetFormat?: SetFormat;
 };
@@ -37,10 +58,7 @@ export type SmartComplementResult = {
     shouldApply: boolean;
     reason?: string;
 };
-/**
- * Get the format for a specific set index
- * Uses finalSetFormat for deciding set if available
- */
+export declare function matchUpConfigFor(matchUpFormat?: string): MatchUpConfig;
 export declare function getSetFormatForIndex(setIndex: number, config: MatchUpConfig): SetFormat | undefined;
 /**
  * Check if a set is tiebreak-only (e.g., TB10)
@@ -80,12 +98,12 @@ export declare function getSetWinner(setIndex: number, scores: {
 /**
  * Determine if match is complete based on sets won
  */
-export declare function isMatchComplete(sets: SetScore[], bestOf: number, exactly?: number): boolean;
+export declare function isMatchComplete(sets: SetScore[], config: MatchUpConfig): boolean;
 /**
  * Get the match winner based on sets won
  * Returns undefined if match is not complete
  */
-export declare function getMatchWinner(sets: SetScore[], bestOf: number, exactly?: number): 1 | 2 | undefined;
+export declare function getMatchWinner(sets: SetScore[], config: MatchUpConfig): 1 | 2 | undefined;
 /**
  * Calculate the complement score for smart complement entry
  * Returns null if no predictable complement exists

package/dist/components/scoring/logic/irregularEnding.d.ts

@@ -24,27 +24,64 @@
 export declare const NEITHER_SIDE = "NEITHER";
 /** Shown when an irregular ending has been chosen but the winner question is unanswered. */
 export declare const WINNER_REQUIRED_ERROR = "Select a winner";
-/** The statuses whose selection opens the winner question at all. */
+/**
+ * Every irregular ending a set-entry approach offers, in display order.
+ *
+ * ── Why ten, when this list held six ──
+ *
+ * It held six because those are exactly the keys the factory's scoring policy can refine with
+ * `matchUpStatusCodes`, the reasoning being that a status with no code group cannot carry a reason.
+ * That is true but it was the wrong list to derive a VOCABULARY from, and the cost was measurable:
+ * `freeScoreApproach` has always parsed ten, so four statuses were typeable in one approach and
+ * unreachable in the other three. Rotating between approaches could therefore show an ending that
+ * could not be re-selected. The four additions (SUSPENDED, IN_PROGRESS, AWAITING_RESULT,
+ * DEAD_RUBBER) simply carry no reason, which is the designed quiet state, not a defect.
+ *
+ * Two things checked while widening, recorded because neither is visible from here:
+ *
+ * - `WITHDRAWN` is NOT a factory matchUpStatus (`matchUpStatusConstants.WITHDRAWN` will not even
+ *   compile), yet the USTA policy keys a seventh `matchUpStatusCodes` group with it, from
+ *   `entryStatusConstants`. This comment previously called that "a code group no status can reach"
+ *   and a factory problem. Both halves were wrong, and this is settled, twice over:
+ *
+ *   CA, 2026-09-27: "WITHDRAWN is a statusCode on a WALKOVER... WALKOVER (withdrawn injured or
+ *   withdrawn ill)" — a withdrawal is expressed AS a walkover, and the WALKOVER group already ships
+ *   that expression as `W5` / "Wo/Withdrawn". CA, 2026-09-19: the WALKOVER group records "a match
+ *   that did not happen because someone withdrew", a RESULT; the WITHDRAWN group records "the
+ *   withdrawal itself", an ENTRY action belonging to the entries UI. Same reasons, two events, two
+ *   surfaces — which is why the groups are label-for-label parallel and must NOT be merged.
+ *   `statusCodes.test.ts` holds that, including the measurement that refutes merging them.
+ * - The ten partition PERFECTLY onto the factory's own classification: three directing, seven
+ *   non-directing, with nothing in both and nothing in neither. The `endingPartition` test asserts
+ *   this rather than trusting it.
+ *
+ * Ordered so the three that name a winner come first, then the three an operator reaches for most
+ * often mid-tournament, then the remainder.
+ */
+export declare const SELECTABLE_ENDINGS: string[];
+/**
+ * The statuses whose selection opens the winner question at all.
+ *
+ * DERIVED from the factory's `directingMatchUpStatuses` rather than hand-listed, because "does a
+ * winner advance out of this status" is the factory's question to answer and it already answers it.
+ * Hand-adding a status to two sets is precisely where a mistake hides, and the eleventh ending
+ * should classify itself rather than wait for someone to remember both places.
+ */
 export declare const WINNER_REQUIRING_STATUSES: Set<string>;
 /**
  * Endings that resolve nobody: the match did not produce a result, so there is no winner to name
- * and no winner question to answer. The factory classifies these as non-directing
- * (`nonDirectingMatchUpStatuses`) — nothing advances out of them.
+ * and no winner question to answer. Nothing advances out of them.
  *
  * These are NOT a smaller version of the winner-requiring endings. Asking "who won an abandoned
  * match" is not a question with a missing answer; it is not a question. So unlike a walkover with
  * no winner selection, one of these is valid the moment it is chosen.
- */
-export declare const NON_DIRECTING_ENDINGS: Set<string>;
-/**
- * Every irregular ending a set-entry approach offers, in display order.
  *
- * These six are exactly the keys the factory's scoring policy can refine with `matchUpStatusCodes`
- * (ABANDONED, CANCELLED, DEFAULTED, INCOMPLETE, RETIRED, WALKOVER), which is why the list is this
- * list: a status with no code group cannot carry a reason, and a code group with no status cannot
- * be reached. Ordered so the three an operator reaches for most sit first.
+ * Also derived, and the complement of `WINNER_REQUIRING_STATUSES` over `SELECTABLE_ENDINGS` — but
+ * computed independently from `nonDirectingMatchUpStatuses` rather than as `!winnerRequiring`, so
+ * that a status the factory somehow classifies as NEITHER shows up as a test failure instead of
+ * being silently swept in here.
  */
-export declare const SELECTABLE_ENDINGS: string[];
+export declare const NON_DIRECTING_ENDINGS: Set<string>;
 /** Whether choosing this ending obliges the operator to answer the winner question. */
 export declare function requiresWinner(selectedOutcome: string | undefined): boolean;
 /**
@@ -57,12 +94,52 @@ export declare function requiresWinner(selectedOutcome: string | undefined): boo
  * score is real. The same goes for `RETIRED` — a retirement keeps whatever was played, and needs no
  * completed set to be a valid result.
  *
- * `CANCELLED` and `DEAD_RUBBER` are deliberately NOT here even though this repo's `validateScore`
- * strips scores for them. They are unreachable from the set-entry approaches today (only freeScore
- * parses them) and the factory does not blank scores for them, so adding them here would be a
- * guess. Revisit when the status list widens — see Mentat SCORING_MODAL_STATUS_CODES.md M2.
+ * ── CANCELLED and DEAD_RUBBER are here now, and that is a CLIENT policy ──
+ *
+ * They were held out on the stated grounds that they were "unreachable from the set-entry approaches
+ * (only freeScore parses them)", with a note to revisit when the vocabulary widened. Two corrections
+ * to that, found on widening it:
+ *
+ * 1. CANCELLED was never unreachable — it has been in `SELECTABLE_ENDINGS` all along and renders as
+ *    a radio in both Dynamic Sets and Dial Pad. Only DEAD_RUBBER was genuinely out of reach.
+ * 2. The rule was not absent, it was TRIPLICATED, and the three copies disagreed:
+ *
+ *        NO_SCORE_STATUSES          WALKOVER  DOUBLE_WALKOVER
+ *        validateScore              WALKOVER  CANCELLED  DEAD_RUBBER
+ *        freeScore display          WALKOVER  CANCELLED  DEAD_RUBBER
+ *
+ *    No copy held all four, and the two that agreed with each other both omitted DOUBLE_WALKOVER.
+ *    This set is now the single one, and CA settled its contents (2026-09-27): selecting Cancelled
+ *    or Dead Rubber clears any partial score present.
+ *
+ * Note what that means and does not mean. The FACTORY blanks scores for `{WALKOVER,
+ * DOUBLE_WALKOVER}` only (`modifyMatchUpScore.ts:236`, verified) — `removeScore` is its separate
+ * lever for anything else. So nothing server-side enforces the clearing of CANCELLED or DEAD_RUBBER;
+ * the client simply never submits a score for them, which reaches the same place. Do not "correct"
+ * this set toward the factory's: it is deliberately wider, and the widening is the policy.
+ *
+ * Still NOT here, and each for a reason worth keeping: `DEFAULTED` / `DOUBLE_DEFAULT`, because a
+ * player can default part-way through a match that was genuinely played; `RETIRED`, which keeps
+ * whatever was played; and ABANDONED / INCOMPLETE / SUSPENDED, where the partial score is the entire
+ * content of the result — "6-4 3-2, suspended" says when it was suspended.
  */
 export declare const NO_SCORE_STATUSES: Set<string>;
+/**
+ * Endings a typed score legitimately survives alongside.
+ *
+ * The Dial Pad clears the selected ending when a digit is typed — the operator is starting over —
+ * and must not do that for an ending whose whole meaning includes a partial score. It decided this
+ * by asking `NON_DIRECTING_ENDINGS`, which is a DIFFERENT question: "does anyone advance" is not
+ * "is there a score". The two happened to coincide across the old six. They do not across the ten:
+ * DEAD_RUBBER and CANCELLED are non-directing yet carry no score, so the old gate would have
+ * preserved an ending that had just discarded the digits being typed.
+ *
+ * So it is stated as its own predicate over both axes, and the `endingPartition` test pins the case
+ * that made the difference.
+ */
+export declare const SCORE_PRESERVING_ENDINGS: Set<string>;
+/** Whether a typed score should be kept when this ending is selected. */
+export declare function coexistsWithScore(selectedOutcome: string | undefined): boolean;
 /**
  * Whether this ending means "no score exists", so score validation must be skipped rather than run
  * and then overridden.
@@ -139,3 +216,66 @@ export declare function resolveIrregularEnding(params: {
  *   `error: 'At least one set is required'` was the symptom of exactly that missing check.
  */
 export declare function applyIrregularEndingToValidation(validation: any, selectedOutcome: string | undefined, winnerSelection: WinnerSelection): IrregularEndingResolution;
+/**
+ * What the controls should show for a matchUp that already carries a result.
+ *
+ * The documented INVERSE of `resolveIrregularEnding`. That function was hoisted here because three
+ * approaches each carried their own copy of the forward rule and disagreed; the inverse was left
+ * behind in each of them and diverged the same way. Measured before this existed:
+ *
+ *   - `dynamicSetsApproach` restored all six endings and both double exits;
+ *   - `dialPadApproach` restored only RETIRED / WALKOVER / DEFAULTED, so a saved ABANDONED,
+ *     CANCELLED or INCOMPLETE re-opened reading as COMPLETED — and re-submitting silently replaced
+ *     a non-directing status;
+ *   - `freeScoreApproach` used a third mechanism entirely;
+ *   - `inlineScoringApproach` discarded the saved result by construction.
+ *
+ * Round-tripping is the property that matters, and it is the one a test can hold: for every status
+ * in `SELECTABLE_ENDINGS`, `resolveIrregularEnding(hydrateIrregularEnding(m))` must return the
+ * status `m` was saved with.
+ *
+ * ── What each branch means ──
+ *
+ * A **double exit** is stored as its own status and carries no `winningSide`, so it inverts to the
+ * base ending plus an explicit `NEITHER_SIDE` — the tri-state's third value, recovered rather than
+ * guessed. A **non-directing** ending (ABANDONED, CANCELLED, INCOMPLETE) resolves nobody, so its
+ * winner is `undefined` and must stay that way; reading a stray `winningSide` back onto one would
+ * re-introduce the fail-open shape this module exists to prevent. Anything else — COMPLETED,
+ * TO_BE_PLAYED, IN_PROGRESS, a status this vocabulary does not offer, or no matchUp at all —
+ * inverts to COMPLETED with no winner, which is the inert state the controls open in.
+ *
+ * Deliberately NOT inferred: a `winningSide` present on a status that requires one is trusted, but a
+ * MISSING one is returned as `undefined` rather than defaulted. An unanswered winner is the
+ * fail-closed state (`WINNER_REQUIRED_ERROR`), and it must survive a save/reopen cycle as unanswered.
+ */
+export declare function hydrateIrregularEnding(matchUp?: {
+    matchUpStatus?: string;
+    winningSide?: number;
+}): {
+    selectedOutcome: string;
+    winnerSelection: WinnerSelection;
+};
+/**
+ * Display labels for every selectable ending, with locale overrides applied.
+ *
+ * Shared because it was not: Dynamic Sets and Dial Pad each kept their own map covering only the
+ * statuses they offered, and Dynamic Sets read it as `ENDING_LABELS[value]` with NO fallback — so
+ * widening `SELECTABLE_ENDINGS` without this would have rendered four radios labelled `undefined`.
+ * One map means an eleventh ending is either labelled or caught by `everySelectableEndingIsLabelled`.
+ *
+ * The fallback is the raw status rather than a blank, so an unlabelled ending is visibly wrong in the
+ * UI rather than invisibly missing.
+ */
+export type EndingLabelOverrides = {
+    retired?: string;
+    walkover?: string;
+    defaulted?: string;
+    inProgress?: string;
+    awaitingResult?: string;
+    suspended?: string;
+    abandoned?: string;
+    cancelled?: string;
+    incomplete?: string;
+    deadRubber?: string;
+};
+export declare function endingLabels(labels?: EndingLabelOverrides): Record<string, string>;

package/dist/components/scoring/logic/outcomeProjection.d.ts

@@ -0,0 +1,25 @@
+import { ScoreOutcome } from '../types';
+/** The fields a projection may replace. Everything else on the matchUp is carried through as-is. */
+type ProjectableMatchUp = {
+    score?: any;
+    matchUpStatus?: string;
+    winningSide?: number;
+    [key: string]: any;
+};
+/**
+ * The matchUp the next approach should hydrate from.
+ *
+ * Returns the original when there is nothing in progress to carry — the ordinary case on first open,
+ * where the saved matchUp IS the truth.
+ *
+ * ── `winningSide` takes no fallback, and that is the whole care of this function ──
+ *
+ * It is read from the outcome and never from the saved matchUp. If the operator has cleared the
+ * score, the outcome carries no winner, and falling back to the stored one would put back a winner
+ * they had just removed — an unanswered question read as a particular answer, which is the fail-open
+ * shape (Mentat architectural standard A3) that `irregularEnding.ts` exists to prevent, one field
+ * over. `score` and `matchUpStatus` DO fall back, because an outcome that asserts neither is not
+ * claiming the match has no score or no status; it is simply not speaking about them.
+ */
+export declare function projectOutcomeOntoMatchUp<T extends ProjectableMatchUp>(matchUp: T, outcome?: ScoreOutcome | null): T;
+export {};

package/dist/components/scoring/logic/scoreEntryModel.d.ts

@@ -0,0 +1,175 @@
+import { hydrateScoreEntryState, ScoreEntryState, SideNumber } from './scoreEntryState';
+import { MatchUpConfig } from './dynamicSetsLogic';
+import { SetScore } from '../types';
+/** The three ways of typing a score. The dialog's own union of the same three names is re-pointed here in S5. */
+export type ScoreEntryApproach = 'dynamicSets' | 'freeScore' | 'dialPad';
+/**
+ * One set as ENTERED, cell by cell. Any cell may be empty, which is how a half-entered set is kept.
+ *
+ * `side1` / `side2` are the set's principal score — games, or the POINTS of a tiebreak-only set, exactly
+ * as the regions' cells hold them. `tiebreak1` / `tiebreak2` are the points that decided an ordinary set
+ * that went to a tiebreak.
+ */
+export type SetEntry = {
+    side1?: number;
+    side2?: number;
+    tiebreak1?: number;
+    tiebreak2?: number;
+};
+/** Which cell of which set an intent is aimed at. A tiebreak-only set has no `tiebreak` cells. */
+export type CellRef = {
+    setIndex: number;
+    side: SideNumber;
+    kind: 'games' | 'tiebreak';
+};
+export type ScoreEntryModel = {
+    matchUpFormat: string;
+    approach: ScoreEntryApproach;
+    /** Exactly the set count the format plays, every entry possibly empty. */
+    sets: readonly SetEntry[];
+    /** The existing pure ending engine, folded in unchanged. */
+    ending: ScoreEntryState;
+};
+/** The ways an ending is chosen, one per transition in `scoreEntryState.ts`. */
+export type EndingIntent = {
+    kind: 'side';
+    sideNumber: SideNumber;
+    status: string;
+} | {
+    kind: 'match';
+    status: string;
+} | {
+    kind: 'bothSidesOut';
+} | {
+    kind: 'reasonCode';
+    code: string | undefined;
+};
+export type CreateScoreEntryModelParams = {
+    matchUpFormat?: string;
+    approach?: ScoreEntryApproach;
+    /** A saved score to open with, in factory shape. */
+    sets?: SetScore[];
+    /** A saved matchUp whose outcome hydrates the ending — see `hydrateScoreEntryState`. */
+    matchUp?: Parameters<typeof hydrateScoreEntryState>[0];
+};
+/** What a model with no format opens under. The same fallback `freeScoreRegion` and `matchUpConfigFor` use. */
+export declare const DEFAULT_MATCH_UP_FORMAT = "SET3-S:6/TB7";
+export declare function createScoreEntryModel(params?: CreateScoreEntryModelParams): ScoreEntryModel;
+export type TypeDigitIntent = {
+    cell: CellRef;
+    digit: number;
+    /**
+     * Derive the OTHER side from what was typed, where the format makes that a single answer.
+     *
+     * For a games cell this is the smart complement — a `4` typed into an EMPTY cell writes `6` opposite,
+     * over whatever the other cell held: the inference is about the pair. Whether to offer it again for
+     * the same set is the caller's policy. For an ordinary tiebreak it derives the
+     * winner's points from the loser's, and fires only from the games LOSER's cell, because a winner's 7
+     * could have beaten anything. For a tiebreak-only set it derives the other side from the one typed —
+     * CA's rule for the Dial Pad, which always asks; Dynamic Sets asks while its Smart toggle is on.
+     */
+    complement?: boolean;
+};
+/**
+ * Append a digit to a cell, as a keystroke does.
+ *
+ * Refused — the same model comes back — when the digit could not become a legal score: past the
+ * ceiling for a games cell, or past two digits where no ceiling exists. Refusal is what lets a keypad
+ * move on to the next cell rather than the model guessing.
+ *
+ * The ceiling is `getMaxSetScore`'s, given the OPPONENT's games where they are in: 7 in a set to six,
+ * tightened to 6 for a side facing 3 — 7 is reachable only through a tiebreak at six-all — and left at
+ * 7 for a side facing 5, since 7-5 needs no tiebreak. That last answer is `#5043(factory)`, merged
+ * 2026-09-30; this module is written to the fixed factory, and a `7` typed against a `5` is pinned.
+ */
+export declare function typeDigit(model: ScoreEntryModel, intent: TypeDigitIntent): ScoreEntryModel;
+/**
+ * Write a whole value into a cell, as setting an input's value does. `undefined` empties it.
+ *
+ * Nothing is clamped or derived: the value recorded is the value given, and whether it is legal is
+ * `error`'s question. A keystroke goes through `typeDigit`, which is where the derivations live.
+ */
+export declare function setCell(model: ScoreEntryModel, cell: CellRef, value: number | undefined): ScoreEntryModel;
+export declare function clearCell(model: ScoreEntryModel, cell: CellRef): ScoreEntryModel;
+/**
+ * Empty every set and keep the ending: what a score-clearing ending does to the cells.
+ *
+ * CA, 2026-09-30: *"when I enter set score(s) and then select (Walkover) the set score(s) should
+ * clear."* The card calls this when the chosen ending carries no score, having first read `scoreString`
+ * for the band. Final, like `[Clear]`: un-choosing the walkover does not bring the score back, because a
+ * remembered score that silently reappears on an approach switch was the worse bug.
+ */
+export declare function clearScore(model: ScoreEntryModel): ScoreEntryModel;
+/** Empty every set and un-choose the ending: the card's `[Clear]`. Format and approach stay. */
+export declare function clearAll(model: ScoreEntryModel): ScoreEntryModel;
+/**
+ * Choose (or un-choose) an ending, delegating to `scoreEntryState.ts` — every control there is a
+ * toggle, and that is preserved.
+ *
+ * The SETS are left exactly as they are, even for an ending that carries no score. The card today
+ * clears the region on a walkover and keeps the string aside for the band; here the selectors suppress
+ * the score while such an ending is chosen (`scoreString` answers nothing, `discardedScore` names what
+ * was typed) and it comes back if the ending is un-chosen. Keeping the keystrokes is the point of the
+ * model; whether the card should ALSO clear explicitly is S5's decision, and `clearAll` is there for it.
+ */
+export declare function chooseEnding(model: ScoreEntryModel, intent: EndingIntent): ScoreEntryModel;
+/**
+ * Move to another format, keeping what the new format has not invalidated.
+ *
+ * `retainScoreForFormat` decides, given both formats: a set whose position keeps the same rule survives
+ * finished or not, a set whose rule changed must stand as a complete legal set, and everything after the
+ * first casualty goes with it. It keeps a PREFIX, so the entries are cut to its length rather than
+ * rebuilt from its output — the operator's cells survive untouched. The array is then resized to the
+ * new format's set count.
+ */
+export declare function changeFormat(model: ScoreEntryModel, matchUpFormat: string): ScoreEntryModel;
+/** Change how the score is typed. A no-op on the score itself: the sets are the sets whichever region shows them. */
+export declare function switchApproach(model: ScoreEntryModel, approach: ScoreEntryApproach): ScoreEntryModel;
+/**
+ * The index of the set that decides the match, or `undefined` while nothing does.
+ *
+ * Asked of the factory prefix by prefix, so that a decision reached at set 2 is found even when a stale
+ * set 3 would make the whole array read as undecided — measured: `analyzeMatchUp` on `6-2 6-2 6-3` with
+ * three winning sides answers NO winner, because three is not `setsToWin`.
+ */
+export declare function decidingIndex(sets: readonly SetEntry[], config: MatchUpConfig): number | undefined;
+/** The sets with BOTH principal cells in, as the factory reads them, positioned by `setNumber`. */
+export declare function enteredFactorySets(sets: readonly SetEntry[], config: MatchUpConfig): SetScore[];
+/**
+ * One entry in the factory's shape.
+ *
+ * `buildSetScore` derives the winning side and the tiebreak pair from the loser's points, which is the
+ * contract this module keeps: the lower of two tiebreak cells is the loser's. A cell that is empty stays
+ * empty in the output — it is not read as 0, which is what let a half-entered set claim `6-0`.
+ *
+ * A tiebreak-only set is built here rather than by `buildSetScore`. When this was written that function's
+ * winner rule was a hand-rolled "both sides above zero and unequal" (a `3-1` won, a `10-0` not); it asks
+ * the factory now too, and this path simply never left. The set's winner is `analyzeSet`'s, given the
+ * points AS points — `getSetWinner` would hand them over as games, which a tiebreak-only format has no
+ * rule for.
+ */
+export declare function toFactorySet(entry: SetEntry, index: number, config: MatchUpConfig): SetScore;
+/**
+ * Replace every set from a factory-shaped array: the Free Score boundary, where TEXT becomes sets.
+ *
+ * Free Score keeps the text as the field's own value while it is being typed — a half-typed `6-4 re` is
+ * nothing the model can represent — and commits here at the points where the text parses to sets. The
+ * same seeding and the same invariants as opening a saved score: a set past the decider is trimmed.
+ * The same model comes back when nothing changed, so a keystroke inside a word is not a transition.
+ */
+export declare function replaceSets(model: ScoreEntryModel, sets: SetScore[]): ScoreEntryModel;
+export declare function readCell(entry: SetEntry, cell: CellRef): number | undefined;
+/** The side that lost the set on games, or `undefined` while the games are level or not both in. */
+export declare function gamesLoser(entry: SetEntry): SideNumber | undefined;
+/** Whether both principal cells are in — the regions' `bothEntered`. */
+export declare function isEntered(entry: SetEntry): boolean;
+/** Whether the set holds anything at all, in any cell. */
+export declare function isEmptyEntry(entry: SetEntry): boolean;
+/**
+ * How many sets the format can hold: every set of an `exactly` format, otherwise the best-of. An
+ * aggregate format with a final tiebreak holds one more, its sudden-death decider, which is set N + 1
+ * and never one of the N (factory #5166; CA, 2026-10-04). It opens only on a level total.
+ */
+export declare function setCountOf(config: MatchUpConfig): number;
+/** The set number of an aggregate format's final-tiebreak decider, or `undefined` when it has none. */
+export declare function deciderSetNumberOf(config: MatchUpConfig): number | undefined;